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The Rub^iy^t of Programmer 
Khayyam 


Awake! For Morning’s fickle hand doth load 
Updated software in the daylight mode. 

Return from sluggish subroutine of night: 

DIM the array, but brilliant the code! 

Myself when young did frequently frequent 

The data-punching rooms, and heard great argument; 

But evermore it seemed I must emerge 
By that same interface wherein I’d went. 

Ah, but my computations, people say. 

Process the text to clearer meaning? Nay, 

Though Man may seek the symbols to construe 
The Greater Editor will have his way. 

The User programs while the disk-drives whisk; 

Taps the mad keyboard of a mind at risk. 

The work of years comes suddenly to naught 
As random noise corrupts the floppy disk. 

Some for the glories of this world, and some 
Sigh for a pointer to the world to come. 

Ah, seize the output, let the record go. 

Nor heed the rumble of magnetic drum! 

A User-Manual ’neath a labelled tree, 

A pint of beer, a ploughman’s Lunch—and Thee! 

What care I then for megabytes? 

Thy tiniest bits yield megabytes for me. 

The moving cursor writes, and having writ 
Moves on: nor all your piety nor wit 

Shall lure it back to cancel half a line 
Nor all your Tears wash out a word of it. 

But wait! say ye: The console’s cursor keys 
Can Backspace, Rubout, Edit as we please? 

Not so! These merely tidy the display: 

Still the grim input’s in the memories. 

Some peek the ROM of Time’s predestined flight; 
Some seek within Life’s RAM new lines to write. 

In vain each strives t’assemble faultless code. 

For still Death’s Digits poke the final byte. 
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Preface 


In a way, this is a sequel to our book TimexISinclair 1000 Programs, Games and 
Graphics, which henceforth we shall refer to simply as Timex ISinclair 1000, It’s 
designed to do two things: exploit the extra power of a 16K-expanded memory, and 
introduce the delights of Z80 Machine Code. 

The principles of good programming are machine-independent, and almost every¬ 
thing in this book applies (subject to minor changes to system variables) to any 
machine built around a Z80 or Z80A CPU: Timex/Sinclair 2000, the Sharp MZ80B or 
MZ80K, the Tandy TRS80, and the Research Machines 380Z, for example. Owners 
of these machines will easily adapt the descriptions given; but for definiteness we 
have chosen to write for the Sinclair ZX81. There is one overwhelming reason for this 
choice. 

As we write, there are over 400,000 Sinclair ZX81s (essentially identical to the 
Timex ISinclair 1000) in existence. This “motorbike of computers” has brought com¬ 
puting into the home in a big way: people who would never have dreamed they would 
even be using a computer now own one—and use it to educate their children, balance 
the household accounts, work out their taxes, play games, and run electric trains or 
photocopiers. 

This book is for those who have mastered the basics, and want to cut their teeth on 
something more substantial. 

One thing you can do is write more complicated BASIC programs—after all, that’s 
why high-level languages like BASIC were invented. To write bug-free programs 
which can be understood and modified without courting the lunatic asylum, you need 
to develop a well-structured style. We pursue this line of thought in the sections on 
Data Structures and Structured Programming. 

You can also go outside BASIC altogether. On the 1000 that means Machine Code: 
the language that the Z80 microchip talks. Often (though not always) Machine Code 
is faster than BASIC: the snag is that you have to do more of the thinking yourself by 
way of compensation. We didn’t think that you’d want to write long Machine Code 
routines at this stage; but we’ve given enough information for you to take several 
steps along that road, so that the more advanced books (listed in the bibliography) 
become accessible. 

One important feature of Machine Code is that it teaches you a lot more about the 
way the computer actually works —and in the coming age of microe very things, that’s 
going to be an important piece of knowledge. 

We’ve included plenty of programs as examples: searching a stock list, enqueuing 
and dequeuing data, pushing on to a stack and popping from one, cataloguing a 
library, a game-tree where the computer works out its own winning strategy, a 
complete text-editor (or word-processor), a simulation study of supermarket check¬ 
outs which applies equally well to allocating hospital beds, and an educational 
program for testing French vocabulary. 

There are Machine Code routines to give the display a checkerboard pattern 
(instantly), or turn it into inverse video (in a flash); to draw lines of characters, to add 



and multiply numbers, to move data around in RAM, to scroll limited regions of the 
screen fast enough to be useful, to scroll sideways, and to renumber BASIC lines. 

The appendices include several tables of useful data: hex/decimal conversion 
(including 2 s complement notation for relative jumps); memory reservation; system 
variable addresses; a summary of Z80 commands; a list of all 694 of the Z80 Opcodes 
There’s a modestly powerful BASIC program called HELPA (Hex Editor, Loader, 
and Partial Assembler) that takes most of the pain out of Machine Code; and an 
accessory called DOWNLOAD which will let you incorporate a Machine Code 
routine into a program loaded from tape (thus passing routines from one tape to 
another via the 1000). 

If you want, you can copy out most of this material and RUN it without worrying 
too much about why it works. But what we hope you will do is work through the 
explanations too. That way, you'll be learning how to write your own programs and 
how to get out of the 16K RAM some of the marvellous things it is capable of 

After all, you want the TimexISinclair 1000 to know who’s boss. 


So far, we’ve referred to ourselves as “we”—but as in 
Titnex!Sinclair 1000, we found this didn’t always work out 
later. So from now on, we’ll refer to ourselves in the singular, 
as “I”. Whenever we say “we”, we’ll mean “I and the 
reader”. It may sound a silly idea, but it’s actually more 
informative that way. 




Data Structures 


There’s a lot more to programming than just knowing the features of a particular 
programming language. For one thing, we need a clear idea of the procedure, or 
algorithm, we are going to employ in solving a given problem. We need to develop ways 
D A algorithm up into chunks small enough to be convenient for coding in 

BASIC, or whatever language we’re using. That’s a topic we’ll come back to. For the 
minute, I m concerned about an even more fundamental problem in program design; 
that of the organization, or structure, of the data which the program is to manipulate. 
Actually, we’re quite used to the idea of imposing a structure on data which we wish to 
handle manually, although we probably wouldn’t give the operation such a grand title 
Think about a bank statement for example: 


Date 

Details 

Debits 

Credits 

Balance 

4/07 

B/FWD 



148.78 

5/07 

897669 

24.48 

_ 

124.30 

9/07 

STILL 

20.00 

_ 

104.30 

1/08 

W.L.LTD 

— 

254.11 

358.41 


It’s clear that the data presented here are structured in a very formal way. Each type of 
data—date, debit, credit and so on—only appears in a given column. There’s even some 
implied organaation-we know, without being told, that the first number in the date is 
j second is the month. (This implicit structure can get us into trouble—if 

the date is read by an American he’ll see it the other way round!) Of course, somebody 
had to decide in the first place that this was a convenient way to present bank statements 
and naturally, he would have asked the question: “How easy is it going to be to deduce 
useM information fi-om this structure?” We, on the other hand, are not interested in 
denvmg information directly fi-om a data structure, but in getting the computer to derive 
the information for us. So we are always going to have to ask the question: “How easy is 

It going to be to write programs to derive useful information fi-om a particular data 
Structure?” 

So it s clear, I think, that it’s important to have the data organized before you start to 
think about the program. 

We’re going to look at a number of common data structures in this book, and to 
descnbe some of the ways in which they are used. The list isn’t exhaustive, and in some 
cases It can be useful to design a structure which is quite novel; so don’t be put off from 
doing so simply because a structure which seems convenient isn’t listed here! 


Sometimes in this section I m going to use “illegal” names for variables—for 
example there’s an array called BIGMAP and a string called MNAME$. Some 
BASICS allow this, but the version used by the 1000 doesn’t. When you key in the 
programs, replace these illegal names by their first letters (unless already used in 
the program, in which case it’s up to you). The aim is to improve the clarity of the 
explanation of the programs by giving a built-in reminder of the variable’s 
meaning. I’ve reminded you the first few times this convention is used. 




Arrays are directly available in BASIC and easy to use: for 
example, to list commercial data. But there are other ways to use 
them—including the analysis of weather-maps. 


1 Arrays 


Some structures are built into languages, and some you have to build for yourself. In 
BASIC, there is only one data structure within the language. It’s called an array, and it 
seems a convenient place to start. 

Let’s review the way we think about the organization of the computer’s memory. We 
could see it as a series: 



of cells, each able to contain a number or string of characters, and each given a name, as 
in the diagram, for example. 

This is fine for many applications, but not for all. For instance, suppose we want to 
input 200 numbers and hold all their values at the same time. It’s no gocki writing: 

10 FORP=1TO200 
20 INPUT X 
30 NEXTP 

because with every loop, a new value will be entered into X, wiping out the old one. So, 
in the end, only the final value in the sequence will be in memory. 

We could write: 


10 INPUT XI 
20 INPUT X2 
30 INPUTX3 
40 INPUT X4 


2000 INPUT X200 

but it would be a pain, and anyway this will occupy a lot of memory within the program 





An array provides us with a way out of the dilemma. BASIC allows us to specify a 
whole block of memory as having just one name: 



The block of memory represented above is called the array X. (It can have any valid 
BASIC name.) 

An array may have any number of memory cells in it, but we have to tell the 
interpreter, at the beginning of the program, how many cells to allocate to it. This is done 
with a DIM (short for dimension) statement. In the above case, X has 6 cells, so we 
would write: 

10 DIMX(6) 

We still need to be able to refer to individual cells, or elements, within X. BASIC allows 
us to talk about X(l), the first element of X; X(2), the second; X(3), the third; and so on. 

Coming back to our original problem, we could write: 

10 DIMX(200) 

20 INPUT X(l) 

30 INPUT X(2) 

40 INPUT X(3) 
etc., etc. 

“Hang on!” You’re all saying. “That’s no better than it was before. In fact, it’s worse 
because there are loads of extra brackets. ” 

True, true. However, the trick is that when we wrote XI, X2, X3 etc., the 1.2 and 3 
are part of the variable names and can’t be altered; but if we write, for instance X(P) 
then the computer sees this as X(l) if P = 1, X(2) if P = 2 and so on. So the value in the 
brackets (called a subscript) can be changed. 

In this case, we want to change the subscript by starting it at 1, and adding 1 to it until it 
reaches 200, and that’s a clear cue for a FOR loop. 

10 DIMX(200) 

20 FORP=1TO200 

30 INPUT X(P) 

40 NEXTP 

Why should we want to store 200 numbers all at once? About the simplest program I 
can think of in which it’s clearly necessary, is one to print in reverse order the numbers 
input to it; 



10 DIMX(200) 

20 FORP =1X0200 
30 INPUT X(P) 

40 NEXTP 

50 FORP = 200X01 STEP-1 
60 PRINT X(P) 

70 NEXTP 

Obviously we can’t print anything until the last number has been read, and we must 
remember all the previous numbers, since they are to be printed subsequently. A more 
practical example is the Bubble Sort. {Timex!Sinclair 1000, p. 78.) 


CALCULATING DISCOUNTS 

Here’s another example of a rather different nature. 

Suppose we run a wholesaling business and we split our customers into the following 
groups, each of which is offered a different discount, shown in brackets: 


1. 

Private 

(0%) 

2. 

Local authority 

(4.0%) 

3. 

Education 

(6.5%) 

4. 

Government 

(7.0%) 

5. 

Trade 

(9.0%) 

6. 

Trade—special contract 

(12.0%) 


What we would like is a program that will accept a customer’s name, his type (1-6), the 
number of items he’s buying and the retail value per item, and print out the details of his 
bill. 

Since the calculations depend on the customer type we might expect to have a series of 
IF statements like: 

50 IFTYPE= ITHEN. . . 

60 IFTYPE = 2THEN . . . 

70 IFTYPE = 3THEN . . . 

This would be tedious but not beyond reasonable bounds. But what if there were 300 
categories? . . . 

Let’s set up an array called DP (for Discount Percentage) like this: 

DP 

DP(1) 

DP(2) 

DP(3) 

DP(4) 

DP(5) 

DP(6) 

Actually, on the 1000 you can’t use more than one letter for an array; but as I said 
above, for clarity I’m going to anyway. If you want to write a program, change DP to D, 
or some other suitable letter. 

Now, if TYPE = 1, the discount value we’re interested in is in DP(1). If TYPE = 2, the 
value we want is in DP(2). In other words the value we are after is always in DP(TYPE)! 


0 

4 

7 

~ 

12 




So the code to input the data and evaluate the discount would look something like: 
80 INPUT N$ 

82 INPUT TYPE 
84 INPUT NUMBER 
86 INPUT VALUE 

90 LET TOTAL = NUMBER * VALUE 
100 LET DISCOUNT = TOTAL * DP(TYPE)/100 


No IPs anywhere! 


5 DIMDP(6) 

10 LETDP(1) = 0 
15 LETDP(2) = 4 
20 LETDP(3) = 6.5 
25 LETDP(4) = 7 
30 LETDP(5) = 9 
35 LETDP(6)=12 

^^is is OK for small arrays but tedious for large ones. An alternative is to use an input 


5 DIMDP(6) 

10 FOR P = 1 TO 6 
20 INPUT DP(P) 
30 NEXTP 


oitK we don t want to execute this routine every time the proeram is run 

although we may wish to do so occasionally, if the discounts change. So we could have? 


1 PRINT “NEW DISCOUNTS? (Y/N)” 

2 INPUT A$ 


3 IFA$ = “N”THENGOTO80 


so 


17 ^ ^ c program jumps round the input routine if the discounts aren’t chanced When 
you save the progr^, the array values are also saved, so this will work for^successive 
runs provided you key m GOTO 1 and not RUN (RUN clears all variable valued 


ARRAYS IN TWO DIMENSIONS 


What I ve been describing so far is called a one-dimensional array or vector. It’s possible 
array or table. We specify such an array by a DIM statement as 


before. For example: 


10 DIMA(3,7) 


specifies an array which looks like: 



In other words, Fve identified for the computer a table having 7 columns and 3 rows. 
There isn’t, though, any standard convention which decrees that the number of columns 
must appear before the number of rows in the DIM statement. It’s the way you think 
about the table that matters. In other words, I could, equally validly, have specified the 
same array by: 

10 DIMA(7,3) 

provided that, in each subsequent reference to the array, I always give the row number 
second, and the column number first. 

The golden rule is: having chosen a convention, stick to it; you’re less likely to make a 
mistake. In this book I’ll use what is probably the commonest convention: give a row 
number first, the column number second. That’s convenient because one-dimensional 
arrays are usually drawn as single columns. 

Now, when we want to refer to a particular cell in the table. A, we can do so by 
specifying the row and column which intersect at that cell; so if we wanted to set the 
shaded cell in the diagram to 24, we could write: 

50 LETA(2,5) = 24 

OK; that’s the basic idea. 

Now, let’s put it to some use. 

Imagine that you are a geographer, who wants to keep a record of the annual rainfall in 
a particular region. There are weather stations dotted around the region, so we might 
have a map which looks like Figure 1.1, in which the region of interest is shown shaded, 
and a star denotes a weather station. 






Obviously, the map is two dimensional, and we can easily represent it in a cor¬ 
responding two-dimensional array by giving each point on the map a numeric code. 
There are only three types of point: 

1. Points inside the region not at a weather station. 

2. Weatherstations. 

3. Points outside the region. 

At the weather stations we know the rainfall so the corresponding position in the array 
can just contain this value (in millimetres). Two values which can’t be confused with a 
rainfall value are now needed to identify points inside and outside the region. Since you 
can’t have negative rainfall, we could choose -2 for a point outside the region and -1 for 
one inside. So an array which models the map would look something like: 


-2 

-2 

-2 

-2 

-2 

-2 

-2 

-2 

-2 

-2 

-2 

-2 

-2 

461 

-2 

-2 

-2 

-2 

-2 

-2 

-1 

-1 

-2 

-2 

-2 

-2 

401 

-1 

-1 

-1 

-2 

-2 

-2 

400 

-1 

-1 

-1 

-1 

-2 

-2 

-2 

-1 

440 

-1 

-1 

480 

-2 

-2 

-2 

420 

-1 

424 

-1 

-1 

484 

-2 

-2 

-2 

-2 

-2 

-2 

-2 

-2 

-2 


Of course, the resulting shape doesn’t look as smooth as the original; in fact, it looks 
rather like a CEEFAX weather map, which is no big surprise, since they are created in 
much the same way. Anyway, we can always improve the appearance (and accuracy) of 
the representation by making the array bigger. 

OK, we’ve managed to store a representation of a map in the computer. So what? 
What’s wrong with a conventional atlas? Nothing, except that a conventional atlas leaves 
you to deduce whatever information you need from it. Now that our representation is 
inside the computer’s memory we can write programs to answer all sorts of questions 
about the map: 

How many weather stations are there? 

What percentage of them have rainfall figures over 410 mm? 

What is the highest recorded rainfall, and where is it? 

What is the area of the region? 

With a map of practical size, it would be very tedious to answer any of these questions 
manually; let’s see how simple it would be to write the programs. 

We’ll suppose that the array has been set up by: 

10 DIMMAP(50,50) 

(again on the 1000 you’d have to replace MAP by, say, M to get the syntax right) and 
that the values have already been input to it. We want to know how many stations there 
are. 

So a rough outline for the procedure would be: 

• Examine a cell. 

• If it contains a non-negative value it’s a weather station so count it. 

• Repeat the process for all cells. 

For a particular cell, somewhere in MAP, whose column value is C and whose row value 
is R, the IF statement we need is: 

1030 IF MAP (R, C)>= 0 THEN LET NWS = NWS + 1 [NWS = number of 

weather stations] 

To deal with all the columns from 1 to 50 in a row R, we need a FOR loop: 
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1020 FORC=1TO50 

1030 IFMAP(R,C)>=0THENLETNWS = NWS+1 
1040 NEXTC 

and to deal with all the rows from 1 to 50, we need a FOR loop round that: 

1010 FORR=1TO50 
1020 FORC =1X050 

1030 IF MAP (R, C)>= 0THEN LET NWS = NWS + 1 
1040 NEXTC 
1050 NEXTR 

If you’ve read Timex/Sinclair 1000 you’ll probably remember this kind of “nested” 
FOR loop construction (I used it to build a graphics rectangular block). 

Now all we need to do is make sure that NWS contains zero to begin with: 

1000 LETNWS = 0 

and print the result out at the end: 

1060 PRINT “NO. OF STATIONS = NWS 

The other three problems I listed are very similar. They all require the same pair of 
FOR loops. The IF statements, and what to do when they are true, change, of course. 
You might like to try them. 



ARRAYS IN THREE DIMENSIONS 

Let’s suppose that our geographer wants to use a bit more raw data. He’s now got rainfall 
figures for each month at each weather station. 

So we need twelve two-dimensional arrays like MAP to represent these data. Each 
array is like a page of an atlas. Shouldn’t we be able to combine the arrays, like binding 
the atlas pages into a book? Well, we can. What we end up with is a three-dimensional 
array, which we could define by: 

10 DIM BIGMAP (50,50,12) 

(replace BIGMAP by B in an actual program, as before) and the third value in the 
brackets represents the number of months. 

We can ask all the same questions as before, and the only change in the programs will 
be that we need another, outside, loop to change the month value. 
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For instance, the new loop could be: 

FOR MONTH = 1 TO 12 

NEXT MONTH 

and the IF statement will look like: 

IF BIGMAP (R, C, MONTH) = . . . THEN ... 

(Of course, some questions, like “How many stations are there?” don’t change with 
time, and if you try this with that program you’ll just get 12 times as many stations as you 
should.) 

How about a routine to tell us the rainfall figure for a particular station in a given 
month? The code could look like this: 

2000 PRINT “ENTER MAP REFERENCE OF STATION (R, C)” 

2010 INPUT R 
2020 INPUT C 

2030 PRINT “ENTER 1ST 3 LETTERS OF MONTH” 

2040 INPUT M$ 

2050 IF M$ = “JAN” THEN LET MONTH = 1 
2060 IF M$ = “FEB” THEN LET MONTH = 2 
2070 IF M$ = “MAR” THEN LET MONTH = 3 


and so on 


2160 IF M$ = “DEC” THEN LET MONTH = 12 

2170 PRINT “REQUIRED HGURE IS:”; BIGMAP (R, C, MONTH); “MM ” 

Lots of IFs again! How can the chunk of code between lines 2050 and 2160 be improved? 

Let’s set up an array of month names (much as we set up the discount table earlier). 
We’ll call it MNAME$ although on the 1000 you’d need to find a single-letter name, 
such as N$. 

MNAME$ 



and then replace the relevant lines with: 

2050 FOR MONTH = 1 TO 12 

2060 IF MNAME$ (MONTH) = M$ THEN GOTO 2170 

2070 NEXT MONTH 

Get it? It searches through the MNAME$ array looking for a match with the input 
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month (M$). When it finds one, the value of the pointer, MONTH, is the numeric 
equivalent. A good maxim is: 

If you’ve just written a piece of code with a lot of similar IF statements, one after the 
other, there was probably an easier way. 


ARRAYS IN HIGHER DIMENSIONS 

Perhaps you noticed that I carefully refrained from saying “A three-dimensional array 
looks like a cube” in the preceding section. Of course, you can think about it like that, 
but it makes it difficult to think about what a four-dimensional array (yes, you can have 
one!) behaves like, because it doesn’t look like anything. We can’t imagine four¬ 
dimensional solids. But that doesn’t imply that it can’t mean something. 

At the risk of flogging a dead geographer, let’s return to our map problem, and 
suppose that now he provides us with the monthly figures for a decade! So we now have 
ten 3D arrays. Why not call that one 4D array, just as we called the twelve 2D arrays one 
3D array. Now we refer to a particular cell in the array as: 

EVENBIGGERMAP (R, C, MONTH, YEAR) 

and we only have to provide the appropriate values of R, C, MONTH and YEAR to 
eliciUhe required data. 

In principle, there’s nothing to stop us having five-, six-, seven- or even higher¬ 
dimensional arrays. Each extra dimension is used to store another attribute such as 
population, death rate, temperature and so on. 

In practice, we’re limited by the available memory. Actually, as far as a 16K 1000 is 
concerned, we had already run out of memory at the 3D stage. It’s easy to calculate: 

We had a 50 x 50 x 12 = 30,000 cell array. 

Each cell occupies 5 bytes, so we’re using 150,000 bytes. A 16K memory has 16 x 1024 = 
16,384 bytes. Oops! 

Of course, we can always make the map smaller to fit it in; 16 x 16 x 12 just fits (but by 
the time the program is stored as well, it might not!). So these refinements are really for 
larger machines, although there can be occasions when a7x7x7x74D array (which is 
getting on for the largest possible in 16K) is useful. 
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Given a list of data, how do you find the item you want? You could 
just read through the whole list. . . but there may be better ways. 


2 Searches 


It’s obvious that one of the most useful things we can do with an array is to search it for 
some particular piece of information; in fact, we’ve already done so, in our examples, 
several times. On each previous occasion, we’ve shown what is known as a linear search, 
so called because every element of the array is examined in turn until the target cell is 
reached. This is fine for small arrays, but with large ones it can be rather time- 
consuming. 

There’s an alternative, known as a binary search, which is faster, provided the data are 
in a known order in the array. Let’s look at an example. Remember my wholesaler with 
his discount system? He’s now getting ambitious. He wants to implement a stores control 
system. Each item he deals with is given a reference number, and the information held 
about each item is the number in stock and the price per unit. 

So we could set up an array like: 


STOCK 


Ref. No. No. in stock Price 


1384 

58 

31.72 

1791 

246 

2.60 

2114 

15 

254.00 

2164 

2486 

0.53 

8561 

1418 

0.16 



Note that the reference numbers are in ascending order. The procedure won’t work 
otherwise. 

Among other routines, we would like one which allows the storeman to enter an item 
reference number, and the system responds by displaying the number currently in stock, 
and the price of the item. 

The way a binary search does this is first to look at the middle row in the table. Thus if 
there are 100 rows, we look at the 50th. (As there isn’t an exact middle row if the number 
of rows is even, the 51st will also work, if you prefer.) If the reference number we’re 
looking for is greater than the one we find here, it can’t be in the lower half of the table, 
so we discard that, and concentrate on the upper half. Now we repeat the process for the 
remaining part of the table. This will chop out one half of the remainder, and continued 
repetition will ultimately narrow the search to one row. 

Sounds long-winded? Well, think about an example. Suppose there are 1000 items in 
the table. According to Murphy’s law the one you’re after is always the last one you look 
at, so a linear search requires an examination of all 1000 items. A binary search removes: 
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500 items from consideration on the 1st test 


250 

/ ! 

f t 

f t 

" " 2nd " 

125 

t t 

t f 

t f 

" " 3rd " 

62 

t f 

t f 

11 

" " 4th " 

31 

t f 

11 

/ 1 

" " 5th " 

15 

t f 

f t 

11 

" " 6th " 

7 

t t 

/1 

11 

" " 7th " 

3 

t t 

r t 

f t 

" " 8th " 

1 

r t 

! / 

11 

M - 9th - 


which means we must find the target on the 10th test (even with Murphy’s pessimism)! 
The diagram below may make the idea a little clearer. 


Target:? 


Mid-pointer 




1 

3 

7 

12 

18 

20 

21 


12 > 7, so ignore the top half of the table. 


Mid-pointer 


1 
3 
7 

^20 , 
21z. 


3 < 7. so ignore the bottom half of the table 


Mid-pointer 



Gotcha! 















Let s write a routine to do this for the STOCK array. (Again we use an illegal name for 
clarity: replace it by S in a program.) We need three pointers; one to the top of the region 
we’re examining (TP), one to the bottom (BP), and the mid-pointer (MP), which is just 
(BP -I- TP)/2. So for an array with 1000 rows we start with: 

25(W LET BP =1 

2510 LET TP =1000 

2520 LET MP = INT ((BP + TP)/2) 

The INT is strictly necessary because otherwise MP may include a decimal part (as here: 
1001/2 = 500.5) which doesn’t make sense. 

Now we need to compare the required reference number (assuming this has already 
been entered into RN) with the reference number in STOCK pointed at by MP: 

2530 IF STOCK (MP, 1) = RN THEN GOTO 3000 

(Remember that item reference numbers are all in column 1.) 

So when we get to line 3000, MP is pointing to the row we want and we’ll be able to 
write: 

3000 PRINT “NO. IN STOCK IS’’; STOCK (MP, 2) 

3010 PRINT “PRICES”; STOCK (MP, 3) 

If the condition isn’t met, however, we need to know if the value pointed to by the 
mid-pointer is greater than the target value and, if so, we chop out the top half of the 
table: 

2540 IF STOCK (MP, 1) > RN THEN LET TP = MP - 1 
On the other hand, the value pointed to by MP might be less than the target value: 

2550 IF STOCK (MP, 1) < RN THEN LET BP = MP -I-1 
Now we need to calculate the new mid-pointer so: 

2560 GOTO 2520 
Tying the whole thing together gives: 

2500 LET BP =1 

2510 LET TP =1000 

2520 LET MP = INT ((BP + TP)/2) 

2530 IF STOCK (MP, 1) = RN THEN GOTO 3000 
2540 IFSTOCK(MP, 1)>RNTHENLETTP = MP-1 
2550 IF STOCK (MP, 1) < RN THEN LET BP = MP + 1 
2560 GOTO 2520 

3000 PRINT “NO. IN STOCK IS”; STOCK (MP, 2) 

3010 PRINT “PRICE IS”; STOCK (MP, 3) 

Of course, there are lots of rehnements you could build in. What happens if you enter a 
nonexistent item reference number, for instance? I’ll leave you to think about that one. 
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“Last in, first out” is the rule for a stack, either in the Tower of 
Hanoi or in a machine code program. Here’s how to build an 
efficient one. 


3 Stacks 


As I’ve said before, arrays are the only data structures inside BASIC. Other structures 
have to be built, usually in terms of arrays. So let’s look first at a structure which is very 
simple to implement in terms of an array, called a stack. 

T^e name “stack” explains its operation pretty well. You can only pile things on top of 
it, and you can only remove items from the top. 

For example, we might start with: 


4 

2 

7 


If we add 9 and 12 (in that order) to the stack we get: 


12 

9 

4 

2 

7 


Remove an item from the stack and we have: 


9 

4 

2 

7 


Obviously what we have is very like a one-dimensional array, but with the added 
restriction that access may only be made at a particular place (the top of the stack). 
Unfortunately, the top moves about inside the array depending on how many items are 
on the stack. So we need a pointer to determine where the top of the stack is. We’ll 
define it to point at the first free location on the stack. 

So now the previous example looks like: 










F 

* 








12 


u 



9 



4 


4 



2 


2 



7 


7 





F 

_ 



12 


9 


4 


2 


7 


Notice that when the 12 is removed from the stack it does not have to disappear from the 
array, because the pointer tells us where the top is to be considered to be. 


STACK ROUTINES 


OK. Let’s try writing BASIC routines to implement a stack. First of all, what routines 
are needed? Well, there are three: 

1. Set up the stack in the first place. We’ll call this INITIALIZE. 

2. Load a value on to the stack. The technical term for this is PUSH. 

3. Remove a value from the stack. This is called POP. 

The INITIALIZE routine can be put right at the beginning of the program; 

10 DIM STACK (20) 

20 LETSP = 20 

For a stack to hold a maximum of 20 items that’s all it is! Putting the stack pointer (SP) to 
20 tells us the stack is empty because it defines STACK (20) to be the first free location. 

The other two routines will be needed throughout the main program and so thev will 
be subroutines. PUSH looks like: 

5010 LET STACK (SP) = V 
5020 LETSP = SP-1 
5030 RETURN 

(assuming that V contains the value to be PUSHed). What’s happening is that the value 
is put into the array where SP is pointing. As that is the first free location, that’s fine. 
Then the stack pointer is moved to point to the next free location. One is subtracted from 
it because of the mental model I have of the stack: 



FULL 


EMPTY 







(There’s nothing to stop you thinking about it the other way round if you prefer; 
provided, of course, you do it consistently.) 

Actually, this diagram gives us a clue to something we haven't considered: what 
happens if the array fills up? When this happens, SP will contain zero, and an attempt to 
execute line 5010 will lead to an error message (report code 3). So we need a line 50W to 
test for this condition: 

5000 IF SP = 0 THEN GOTO 5040 

and: 

5040 PRINT “STACK FULL” 

5050 STOP 

POP will be similar: 

6000 IF SP = 20 THEN GOTO 6040 
6010 LETSP=SP + 1 
6020 LET V = STACK (SP) 

6030 RETURN 

6040 PRINT “STACK EMPTY” 

6050 STOP 

EXAMPLE: THE TOWER OF HANOI 

The “Tower of Hanoi” puzzle provides a simple example of the use of stacks. In its initial 
state, the puzzle looks like this: 


1 2 3 



Figure 3.1 


There are five discs with holes drilled through their centres, mounted on a spindle, with 
the largest disc at the bottom and the smallest at the top as shown in Figure 3.1. A disc 
may be removed from the top of this heap (or any other that forms) and placed on one of 
the other two spindles. 

Obviously, we’ve got three stacks. But there’s an extra constraint: at no stage may a 
larger disc sit on top of a smaller one. The goal is to transfer the whole tower to one of the 
other spindles. 

Our problem is to allow a player to make moves, and display the state of the discs at 
each stage, checking for illegal moves. 

Since there are three stacks we need to make some modifications. We’ll have a pointer 
P to the current stack, so that line 10 becomes 

10 DIM STACK (20,3) 

Also we need three separate stack pointers, which we’ll put in an array called SP: 



15 DIMSP(3) 

20 LETSP(1) = 20 

21 LET SP (2) = 20 

22 LET SP (3) = 20 

(Incidentally weTe only using 20 here because it was used before: a smaller stack would 
be fine.) Now all references in PUSH and POP to STACK(SP) become references to 
STACK (SP (P), P). For instance, line 5010 reads: 

5010 LET STACK (SP(P).P) = V 
and 5020 becomes 

5020 LETSP(P) = SP(P)-1 

Now, before we call PUSH or POP, we have to ensure that P is set to the right stack. 
Here goes. The first job is to set up the left-hand stack (P = 1) to contain the discs. We 
can identify these by the numbers used in Figure 3.1. So: 

100 LETP=1 

110 FOR V = 5 TO 1 STEP - 1 
120 GOSUBPUSH 
130 NEXTV 

Then we find out which stack the player wishes to remove a disc from: 

140 PRINT “WHICH PILE TO BE REDUCED?” 

150 INPUT SR 

and we unstack that value 
160 LETP = SR 
170 GOSUBPOP 

At this stage the required value is in V. We don’t need to test whether there was a disc in 
the stack to remove, because POP tests for an empty stack anyway! Now ask where the 
disc is to be put: 

180 PRINT “WHICH FILE TO BE INCREASED?” 

190 INPUT SI 

Now see if the move is legal. This is going to need some thinking about, so we’ll put off 
the day of reckoning and simply define a subroutine, from which a return only occurs if 
the move is valid: 

200 GOSUB LEGALCHECK 

50 if 210 is reached the move was legal, and we can PUSH into the stack SI, and then 
repeat the whole moving experience... 

210 LETP = SI 
220 GOSUBPUSH 
230 GOTO 140 

It remains to attack LEGALCHECK. We need to confirm that the value on top of the 

51 stack is greater than the value in V. That involves POPping this stack—which will 
overwrite the value in V! So we’ll save V first: 
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300 REM LEG ALCHECK 

310 LETVS = V 

320 LETP = SI 

330 GOSUBPOP 

340 IF V> VS THEN 370 

350 PRINT “ILLEGAL” 

360 STOP 
370 GOSUBPUSH 
380 LETV = VS 
390 RETURN 

Note lines 370 and 380: having popped the value off the stack to examine it we mustn’t 
forget to push it back on, to restore its state. Also, since we moved V out into VS 
temporarily, we have to restore its original value, otherwise the PUSH at line 220 will be 
pushing the wrong thing! 

And now I have to tell you that this won’t work. The reason is that we haven’t 
considered the special case that a stack is empty when something is added to it. Under 
these circumstances the program will never get past line 330, calling POP: it will simply 
object that it can’t, because the stack is empty. TTie simplest thing would be to put “6” at 
the bottom of all three stacks to start with, so that any value in the range 1-5 is allowed to 
stack on top of it. I’ll leave that (or the alternative: test if the stack is empty, and PUSH 
straight away) as an exercise for you. 

I’ll also leave you with the problem of displaying the stacks as the game progresses. 
This can be as simple as printing out the internal values, if you like; or more satisfyingly, 
plotting each disc, using the internal value 1-5 to define the length of the line of graphics 
characters used. 

One final comment: I’ve adopted a new convention here of allowing named sub¬ 
routines (GOSUB, PUSH, etc.) Obviously that’s for improved readability; but it’s quite 
legitimate as a program instruction, provided the variable (here PUSH) is given the 
value of the subroutine’s starting line number. So for instance 

1 LET LEG ALCHECK = 300 

will allow GOSUB LEGALCHECK to be interpreted, correctly, as GOSUB 300. This 
idea can also save work if you decide to change the subroutine addresses. 
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How to store information temporarily and 
process it in the order in which it arrived. 


4 Queues 


Again, the word “queue” describes the operation of the structure well enough. Items are 
added to the queue at one end, but removed from the other. So now we need two 
pointers, one for the head of the queue and the other for the tail, like this: 



head pointer 


tail pointer 


Implementing a queue is very like implementing a stack, but there’s one extra problem, 
to do with testing the queue to see if it’s full. For instance, suppose we add two items to 
the queue shown above, so that the tail pointer is now beyond the array. If we didn’t 
think too c^efully about it, we could use that information to decide that the queue is full. 
Of course, it isn’t, because there’s a spare slot above the head, and if we remove items 
from the queue there will be more available space there, although the tail pointer hasn’t 
moved, and it’s the tail pointer we’re testing to see if the queue is full. 

So let’s rethink the problem. Firstly, when the tail pointer falls off the bottom of the 
array we want it to reappear at the top, so as to use the available array space. In other 
words, the array becomes a circular structure, and both pointers chase each other round 
it. That still leaves the question of how we tell when the queue is full or empty. Let’s 
think about a simple example: 
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HP 



TP 


If we remove two items from this queue, we’ll have to add two to the head pointer and 
the queue will now be empty: 



(For clarity. I’ve removed the 2 and 7 from the array, although, as with the stack, they 
will actually be left there). 

So there’s a nice simple rule to determine when the queue is empty: the head and tail 
pointers are equal. 

Now let’s fill the original queue by adding two values (9 and 4, say) to it. So the tail 
pointer goes back to the beginning of the array and then gets incremented by one: 



HP 


TP 
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Oops! The head and tail pointers point to the same place again, so all our rule actually 
tells us is that the queue is either full or empty. Not much use really . . . 

Never mind! We can get round it quite easily. What we’ve really done so far is roughly 
like taking a snapshot of a motor race and asking somebody to look at it and say which car 
is in the lead. Of course, he can’t, because he doesn’t have any information about how 
many laps each car has done. We’re in a similar position. The pointers could be neck and 
neck (empty) or the tail pointer could be about to lap the head pointer (full). So we don’t 
need to know exactly how many laps each pointer has done, only the difference between 
them. This can only be zero or one, because to allow more would overfill the array. 


QUEUE ROUTINES 

Having dealt with that problem, the rest of the programming is pretty similar to that for a 
stack. Again, we need three routines, called INITIALIZE, ENQUEUE and DE¬ 
QUEUE. As before, INITIALIZE can appear at the beginning of the program: 

10 DIM QUEUE (20) 

20 LET HP =1 
30 LETTP=1 
40 LET LAP = 0 
the ENQUEUE routine is: 

2000 IF HP = TP AND LAP = 1 THEN GOTO 2060 

2010 LET QUEUE (TP) = V 

2020 LETTP = TP+1 

2030 IF TP > 20 THEN LET LAP = LAP + 1 

2040 IFTP>20THENLETTP= 1 

2050 RETURN 

2060 PRINT “QUEUE FULL” 

2070 STOP 

A couple of things to note: 

As for a stack. I’m assuming an array of length 20, and the value to be enqueued to be 
held in V. Line 2000 tests to see if the queue is full. Lines 2030 and 2040 deal with the 
problem of completing a lap. Since two actions are necessary to do this, we can either ask 
the same question twice (as I have) or let: 

2030 IFTP>20THENGOSUB2080 

perform the two actions on 2080 and 2090 and have another RETURN on 2100. 

Logically they are equivalent, but if you spray too many GOSUBs and GOTOs 
around your code, it looks like undisciplined knitting, and becomes very difficult to 
read. 

DEQUEUE takes the form: 

3000 IF HP = TP AND LAP = 0 THEN GOTO 3060 
3010 LET V = QUEUE (HP) 

3020 LETHP = HP+1 
3030 IF HP > 20 THEN LET LAP = LAP - 1 
3040 IF HP >20 THEN LET HP = 1 
3050 RETURN 



3060 PRINT “QUEUE EMPTY’ 
3070 STOP 


See how similar the two subroutines are? There’s a kind of mirror-image symmetry about 
them. The same was true of the PUSH and POP routines. It’s a very common pheno¬ 
menon in routines which do, in some sense, opposite things. The programmer with a 
nose for trouble will worry when symmetry like this isn’t present. It’s not a hard and fast 
rule; just a hunch that comes with experience, but useful nevertheless. 


A FOOTBALL QUEUE 

Here’s an example of how a queue might be used. 

The ABC video printer, used on weekend sport programs to transmit the football 
results, is really just a kind of long-distance typewriter. And, often, it looks like it—with 
a one-finger merchant operating it from the far end. Suppose instead that, when the 
operator types a character, it is not immediately transmitted, but queued. The entire 
queue is dequeued only when the operator hits “return’’. That way “ARSENAL’’ will 
flash on to the screen as a whole word, instead of being laboriously typed A-R-S-. . . 
Here’s the necessary code: 

10 LET EMPTY = 0 
20 LET HP =1 
30 LETTP=1 
40 LETLAP = 0 
110 LETV$ = INKEY$ 

120 IF V$ = “’’ THEN GOTO 110 

130 IF V$ = CHR$ 118 THEN GOTO 160 

140 GOSUB ENQUEUE 

150 GOTO 110 

160 FORI =1 TO 20 

170 GOSUB DEQUEUE 

180 IF EMPTY = 1 THEN GOTO 210 

190 PRINT V$; 

200 NEXT I 
210 PRINT 
220 LET EMPTY = 0 
230 GOTO 110 

There are some slight modifications needed to ENQUEUE and DEQUEUE, because 
we’re dealing with characters, not numbers. In particular V becomes V$, and so on, and 
the arrays become character arrays. When the queue is flushed we don’t want “QUEUE 
EMPTY” appearing on the screen—imagine the viewers’ surprise at this little-known 
team playing against Chelsea—so we replace line 3060 of DEQUEUE by 

3060 LET EMPTY =1 

Now we simply test EMPTY on the return to see if the queue is empty yet; and if it is, we 
start on the next word. 

We are here using EMPTY as a flag: we wave it (i.e. set it to the value 1) to show that 
something interesting has happened. Then, to find out later if it did happen, we just look 
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at the flag. If it’s at 0, then it didn’t happen after all. Flags are important later in the 
machine code chapters. 

At the moment you’ll get a printout like 

ARSENAL 

2 

LIVERPOOL 

3 

because an ENTER is generated at every queue-flushing operation by line 210. (In fact, 
if you’re too slow on the keys, you’ll get AAARRRSSSSSEENNNNAAAALLLL, 
with auto-repeat!) Also, since you can’t input SPACE with INKEY$—it would be 
interpreted as BREAK— you’ll also get 

WEST 

HAM 

4 

QUEENS 

PARK 

RANGERS 

1 

See if you can devise ways round these faults, to give output like 
WEST HAM 4 QUEENS PARK RANGERS 1 
For another example of the use of queues see Checkout, Chapter 9. 



The treasure-hunt principle for easily modified listings. 


5 Linked Lists 


The structures we’ve looked at so far have all had one thing in common; if you know 
where a particular element is, you know where the next one is, because it’s always in an 
adjacent memory cell. But suppose we allowed related data to be sprinkled all over 
memory? (Let’s not worry for the moment about why we might want to.) Then we would 
need some explicit way of finding an item when we know where the preceding one was. 
The diagram below illustrates this in an abstract way. 



The symbols T, E, A, H, C and “space” are arranged in no obvious pattern until you take 
into account that each is associated with a pointer so that provided you start at the T on 
the top line and follow the pointers through to the asterisk, which I’m using as a delimiter 
to mean “end of list”, you get the message:“THE CAT”. It’s the treasure-hunt 
principle, isn’t it? Find an item, and that gives you a clue to the next. 

How do we implement the structure? Well, each element has two components, some 
data and a pointer. So why not have a pair of corresponding one-dimensional arrays 
organized as shown overpage: 
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DATA$ 



so that if we want to print the contents of DATA$ in the right order we need a subroutine 
like: 


1000 LETP=1 

1010 PRINT DATA$(P); 

1020 IF PTR(P) = 0 THEN RETURN 
1030 LETP = PTR(P) 

1040 GOTO 1010 

(Note that I’ve had to use zero, rather than asterisk, for my delimiting pointer because 
PTR is a number array.) 

“Hang on a minute!” You’re all objecting (like mad by now I expect). “You don’t 
need to make all this fuss. You could just print out the contents of DATA$ in a FOR 
loop from 1 to 7.” 

That’s right. But suppose I want to alter the message to “THE BLACK CAT”. Doing 
it the straightforward way. I’d have to move the letters CAT down the array to make 
room to insert BLACK. Using the linked list, all I need to do is to tag BLACK on to the 
end of the array and change one of the original pointers (5) like this: 


DATA$ PTR 

—I I / 


1 

T 


2 

H 


3 

E 


4 

□ 


5 

C 


6 

A 


7 

T 


8 

B 


9 

L 


10 

A 


11 

C 


12 

K 


13 

□ 



^-change 




OK, it wouldn’t have been a great problem to move three letters five places down the 
array, but suppose these were the first words of a five thousand word essay? 

What we’ve just done is to edit a piece of text. That’s the main job of what have come 
to be called “word-processing” programs, and I’ve just introduced the fundamental data 
structure on which most word-processors depend. I don’t want to take this example any 
further just now, because the word-processor case study (Chapter 8) deals with it in some 
depth. 


A LIBRARY CATALOGUE 

However, the linked list is such a useful structure that it’s worth looking at another 
application for it. Let’s suppose that a librarian wants to keep an author index so that 
when a subscriber asks “have you got any other books by Austin P. Goatwhirler?” he 
can answer immediately, even though he is not a Goatwhirler fan himself. 

We might, first of all, hit on the idea of using a simple table like this: 


Name Title 1 Title 2 TitleS 



but, of course, the disadvantage with that is that the number of books which can be 
recorded for each author is fixed, and some authors may only have one book in the 
library, in which case a lot of memory is being wasted, while others may have more books 
than we can allocate space for. 

An organization in which each author has his own linked list of book titles gets over 
this problem. There’ll have to be an author array with a corresponding pointer array to 
point to the first entries in the book lists like this: 


AUTHORS 

z_ 


FP 


BOOKS 


PTR 


LE CARRE J. 
DEFOE D. 
KAFKA F. 
RUNYON D. 


5 h 
7 


^ THE SPY WHO CAME IN FROM THE COLD 
A SMALL TOWN IN GERMANY 
TINKER TAILOR SOLDIER SPY 
HMOLL FLANDERS 
THE TRIAL 
THE CASTLE 
MON BROADWAY 


L 



2 


3 


0 


0 


6 


0 


0 


To list all the books by a particular author, all we need to do is match the author’s name 
with the corresponding first pointer: 


5(W PRINT “ENTER AUTHOR” 

510 INPUT A$ 

520 FOR P = 1 TO 200 [if there are 200 authors] 

530 IF A$ = AUTHORS (P) THEN GOTO 570 
540 NEXTP 

550 PRINT “THERE IS NO REFERENCE TO THIS AUTHOR” 

560 RETURN 



When we get to line 570, P points to the target author, and also to the corresponding 
position in the FP array. So that FP (P) tells us where to start looking in BOOKS. 

So the rest of the routine looks very like the previous linked list printout program: 

570 LETP = FP(P) 

580 PRINT BOOKS (P) 

590 IF PTR(P) = 0 THEN RETURN 
600 LETP = PTR(P) 

610 GOTO 580 

All this assumes that the AUTHORS, FP, BOOKS and PTR arrays have already been 
correctly set up. Our librarian will not thank us if he has to know about the internal 
structure of his data in the primitive way that we’ve just thought about it. So we need 
another routine which allows him to enter the data in a more natural way, and sets up the 
links that we need automatically. I’ll leave you to think about that problem. It’s quite an 
interesting little project. Just to give you some pointers (pun!) to it. I’ll consider a related 
routine, one to make an insertion of a new book into an existing author catalogue. 

To take a particular example, suppose we add Franz Kafka’s America to the library. 
First, we search the BOOKS array for the first unused element, and insert “AMERICA” 
into it, keeping a note of where it is (element 8, in our example). At the same time we can 
set the corresponding element of PTO to zero, since the new book is now the last entry 
under this author. So PTR (8) = 0 in this case. The only other thing to do is replace the 
old zero delimiter by 8, so that “AMERICA” will be printed after “THE CASTLE” in 
the print routine. Of course, it’s no good just searching the PTR array for a zero, because 
we need the one which terminates Kafka’s novels. So we have to look for KAFKA F. in 
AUTHORS, find 5 in the corresponding FP element, look in PTR (5), find 6, look in 
PTR (6), find zero and replace it by 8. 

The routine is: 


1500 

1510 

1520 

1530 

1540 

1550 

1560 

1570 

1580 

1590 

1600 

1610 

1620 

1630 

1640 

1650 

1660 


PRINT “ENTER AUTHOR ” 
INPUT A$ 

PRINT “ENTER NEW TITLE ” 
INPUT NTS 
FORP= 1TO1000 


[if BOOKS is 1000 elements long] 


IF BOOKS (P) = “ ’’THEN GOTO 1570 
NEXTP 

LET BOOKS (P) = NTS 
LETPTR(P) = 0 
FORI = ITO 200 

IF AS = AUTHORS (I) THEN GOTO 1620 
NEXT I 

IF PTR (I) = 0 THEN GOTO 1650 
LET I = PTR (I) 

GOTO 1620 
LET PTR (I) = P 
RETURN 


> 


search for 
1st null entry 
insert new 
title 

search for 
author 

search for 

terminating 

zero 


> replace it with P 
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MENUS 

We’ve got the basis, here, of a genuinely useful data-retrieval system. Obviously, there 
are a lot more routines which would be necessary (for instance we don’t have a way of 
deleting an entry at the moment), and we need a way of linking them together. A 
convenient technique is to use a menu. When the program is run, it first displays on the 
screen a list of options which it can execute. So, in this example, we might get something 
like: 


LIBRARY RETRIEVAL SYSTEM 


OPTIONS ARE: 

1. SET UP NEW LIBRARY 

2. INSERT 

3. DELETE 

4. SEARCH 

ENTER OPTION (1-4): 

When you enter one of the options you may get a sub-menu. In this case if 2 is entered, 
you could get: 

INSERT ROUTINE 


OPTIONS ARE: 

1. AUTHOR INSERT 

2. NEW TITLE 

ENTER OPTION (1/2): 

This way, all the routines can be written as independent subroutines, the menus can just 
be printed out at the beginning, and calling the right subroutine can be achieved with: 

50 GOSUB 1000 * OPT 

where OPT is the value input at the bottom of the menu. We just have to ensure that the 
SET UP NEW LIBRARY routine is at 1000, INSERT is at 2000, DELETE is at 3000 and 
so on. The INSERT routine would have something similar: 

1020 GOSUB (1000 + OPT * 300) 

The AUTHOR INSERT routine would have to be at 1300 and the NEW TITLE routine 
at 1600. 

There’s more about breaking programs down into manageable chunks in the section 
on Structured Programming. 
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There are plenty of other features which you can add to this embryo data retrieval 
system. How about a subject-index, for example? A SUBJECTS array will be necessary 
(with its associated FP array), behaving just like the AUTHORS array. There’s no point 
in repeating the information in BOOKS, but the linking pointers will be different, so we 
need a new PTR array. 

At the moment, it is not easy to find out who wrote a particular book. Why not have a 
set of pointers pointing from BOOKS into AUTHORS to handle that? 

And so on, and so on. But I’ll hand over to you, at this point. There’s a lot of 
interesting programming here, and a really useful program at the end of it. 

Project 

I’ve alluded several times in this section to problems in Stock Control. It isn’t particularly 
difficult to write a suite of programs to handle the stock for a small business. 

You’d start by considering what kinds of data are required, and a suitable structure for 
these. You’d certainly need things like part number, part description, unit cost, number 
in stock, location (bin number), reorder level, reorder number, supplier’s address. The 
chances are that arrays organized as tables will do for this, unless there are alternative 
suppliers of some items, in which case linked lists would be convenient. 

TTien you’d need routines like these: 

1. Add new stock. 

2. Remove stock. 

3. Interrogate system for (a) number in stock of a given item, 

(b) location of a given item. 

4. Add new item. 

5. Delete item. 

6. Change supplier of item. 

7. Change price of item. 

8. Generate orders for items at below reorder level. 

9. Generate financial reports (such as average cash tied up in stock). 

Like all “real” projects this can grow like Topsy. The important thing is to make sure 
that each routine is independent of the others so that new ones can be added, and old 
ones can be edited, with the minimum of bother. 
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An old genealogist’s trick, 

for tasks which branch at every stage. 


6 Trees 


A tree is a structure consisting of nodes and branches. Each node (except one) has exactly 
one branch entering it, and may have any number, including zero, leaving it. The 
exception is the root, which has no branches entering it. A node which has no branches 
leaving it is called a leaf. So, a tree might look like: 



The lettered circles are all nodes, joined by straight line branches. “A’’ is the root and 
“D”, “E”, “F”, “G", “I” and “J” are all leaves. Implementing this structure isn’t much 
different from implementing a linked list, except that now there is a variable number of 
pointers from each node. In this case there are never more than three, so a three-column 
array will do: 

DATA$ PTR 


1 

A 


\ 

2 

B 


4 5 6 

3 

C 


00 

4 

D 


0 0 0 

5 

E 


0 0 0 

6 

F 


0 0 0 

7 

G 


0 0 0 

8 

H 


9 10 0 

9 

I 


0 0 0 

10 

J 


0 0 0 





A FAMILY TREE 


There are some very straightforward applications for trees, and some less obvious ones. 
Let’s look at a straightforward one first—the representation of a family tree. 

This is another data retrieval problem, really. We store the family tree, and then want 
answers to questions like “who was X’s maternal grandfather?” So we might consider an 
organization like: 



In other words, Jim and Mary are Bill’s parents, Albert and Edith are Mary’s and so on. 
Of course, it’s an incomplete representation, because there is, for example, no way of 
telling whether Albert and Edith had more than one child. It’s really just that part of the 
complete tree which affects Bill directly. To get more detail, we would need jX)inters 
from each node to other trees showing the offspring of that node’s brothers and sisters; 
which would lead to other trees in the same way. Boggle, boggle! Let’s keep it simple. 

The internal structure looks like: 


DATA$ PTR 

\ _. _ / 


BILL 


2 3 

MARY 


4 5 

JIM 


6 7 

EDITH 


8 9 

ALBERT 


10 11 

MARTHA 


12 13 

TOM 


14 15 

MABEL 


0 0 

GEORGE 


0 0 

EVE 


0 0 

JOHN 


0 0 

ZOE 


0 0 

HARRY 


0 0 

SUSAN 


0 0 

PETER 


0 0 








SETTING UP A TREE 

Genealogists are, in my experience, no more sympathetic to the problems of computer 
programmers than librarians are, so we’ll need a way to set up this structure. Suppose we 
ask the user to enter the name of a member of the tree, together with his (or her) mother 
and father, in that order. We don’t ask any more than this; that is, we don’t insist that 
BILL is the first entry, for instance. 

So we have: 

100 PRINT “ENTER NAME” 

110 INPUT N$(l) 

120 PRINT “ENTER MOTHER ” 

130 INPUT N$ (2) 

140 PRINT “ENTER FATHER” 

150 INPUT N$ (3) 

Now we insert N$ (1), N$ (2) and N$ (3) into the DATA$ array. Anywhere will do, 
because the pointers are going to take care of the links, so the simplest thing is just to 
load them into the first three available spaces. Rather than have to read DATA$ every 
time this is done to find some free space, we could keep a pointer to the first free 
element. This will be 1 to begin with so: 

90 LET PFF = 1 [pointer to first free] 

Hang on though! What if one (or even all) of these names have been entered before? 
We don’t want double entries, so we’ll have to search the array for each name in turn: 

160 F0RI=1T03 
170 LETP(I) = 0 
180 FOR R = 1 TO 15 

190 IFDATA$(R) = N$(I)THENLETP(I) = R 
200 NEXTR 
210 NEXT I 

It may have been worrying you why I bothered to enter the names into a new array (N$). 
Can you see that it’s saved repeating lines 170 to 200 for three sets of values? 

What’s the inside loop doing? Well, if the name isn’t already in DATA$, P (I) is left at 
zero. Otherwise, P (I) contains the row where the name is to be found. 

Let’s follow this through so far with the example. We enter BILL, MARY, JIM. The 
program searches for these names and doesn’t find them so we’re left with: 


N$ 

\ 


P 

\ 


1 

BILL 


0 

2 

MARY 


0 

3 

JIM 


0 


We can use this to make the rule: “If an element of P contains zero, the corresponding 
element of N$ can be entered into DATA$, because it hasn’t occurred before”. 
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Now we enter MARY, EDITH, ALBERT. This time N$ and P appear as: 


N$ P 


\ 

I 


1 

MARY 


2 

2 

EDITH 


0 

3 

ALBERT 


0 


So only EDITH and ALBERT need to be copied. As we copy them, let’s keep a 
record of where we put them by holding the row values in the P array: 


220 F0RI=1T03 
230 IF P (1)0 0 THEN GOTO 270 
240 LET DATA$ (PFF) = N$ (I) 
250 LET P (I) = PFF 
260 LETPFF=PFF+1 
270 NEXT I 
So now we’ve got: 


N$ 

\ 


P 


1 

MARY 


0 

2 

EDITH 


4 

3 

ALBERT 


5 


and that tells us that the pointers in row 2 should be 4 and 5, or in general, row P (1) 
contains the pointers P (2) and P (3)! 

All we need to write is: 

280 LETPTR(P(1),1) = P(2) 

290 LETPTR(P(1),2) = P(3) 

That’s broken the back of the problem; now for some tidying up. First we need to loop 
what we’ve got, to allow all the names to be entered: 

300 GOTO 100 

and that means we need a way out of the loop: 

115 IFN$(1) =‘“’’THEN RETURN [or GOTO wherever] 

Finally, we’ve got to dimension all the arrays: 


10 

DIMDATA$(15,10) 

[if no name exceeds 10 letters] 

20 

DIMPTR(15,2) 


30 

DIM N$ (3,10) 


40 

DIM P (3) 





One more thing you should notice: since leaves don’t have pointers leaving them, the 
initial values at leaves in the PTR array are never altered. Since these will be set to zero 
by BASIC when the array is dimensioned, and we’re using zero to indicate “no pointer’’, 
this is fine unless, in the middle of the program, you want to grow a new tree in the same 
array. Then, you would have to zero the PTR array to leave it in the state the “Grow a 
tree” routine expects to find it. It would be safest to do this anyway at the beginning of 
the routine. 

Now we come to a very interesting feature of the program we’ve just written. We have 
assumed throughout that the data are entered in the logical order—first BILL, MARY 
and JIM, then EDITH and ALBERT followed by JIM, MARTHA and TOM etc. but 
actually the order in which the sets of three names are entered doesn’t matter a bit. Try 
it. Key in the program, tack a routine on the end to point to the DATA$ and PTR arrays 
and then enter, for instance, ALBERT, EVE, JOHN, then JIM, MARTHA, TOM, 
then MARTHA, ZOE, HARRY and so on. Of course, the positions of the names in the 
DATA$ array will vary depending on your order of entry, but the pointers will also 
change so that they point to the right names. 

This is nice, because it allows the user to dredge bits of information out of his memory 
in no special order (which is how most of our memories work) and enter them while he 
remembers them. He doesn’t have to form a notion of the tree that we’ve been working 
from. 

Searching the tree for details of a person’s parentage is easy. Find the required names 
in D ATA$. The pointer in column 1 of PTR of that row points to his (or her) mother and 
that in column 2 points to the father. The process can be repeated to look for grand¬ 
parents, great grandparents and so on. I’ll leave the actual coding to you. 
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A common use for trees: storing moves in a game. Backtrack 
through the tree to find a winning strategy. Here the computer 
teaches itself to win at NIM. 


7 Game Trees 


It’s possible to represent the moves in a two-person game in a tree. Let’s look at a simple 
example. I’ll define the rules of a game as follows. 

1. There are two players who take it in turns to move. 

2. The initial state of the game is that five matchsticks lie on a table. 

3. A legal move consists of removing either one or two matchsticks. 

4. A player has won if the other player removes the last match. 

You’ve probably recognized this as a simplified form of Nim (in which there are more 
matchsticks and more options) and if you’ve ever played Nim you’ll know it’s a very 
simple game, so what we’ve got is very simple indeed! 

The tree shows every position that is possible in the game, and links are shown 
between successive possible positions. The letters in the nodes are just references, but 
the numbers indicate the number of matchsticks left at that stage: 



1st player’s move 


2nd player's move 


1st player’s move 


2nd player’s move 


1st player’s move 
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Notice that I haven’t said anything yet about whether a move is good or bad. For 
instance, if the game reaches node E, player 1 certainly isn’t going to remove two 
matches and so reach node K because in doing so he loses! But it is a legal move and the 
tree is only concerned with all possible legal moves. 


WHEN IS A MOVE GOOD? 

Now let’s assign some values to the nodes which indicate the quality of a particular move. 
Obviously, this is easiest at the leaves because we know who’s won. Let’s define a value 1 
to mean player 1 wins and a value — 1 to mean player 2 wins. (I’ve used — 1 out of a feeling 
of symmetry: you could try 0.) 

For instance, node U has the value -1 because player 1 picks up the last match. 
Similarly Q, R, S and T are all set to 1, and K, M and N to -1. In some cases, it’s possible 
to assign values to nodes which aren’t leaves. For example, since node P only branches to 
node U it must have the same value as node U (i.e. -1). This is another way of saying 
that once the game has reached node P, player 2 is guaranteed to win. 

Now we’ll make the assumption that each player plays his best move at each stage. 
That means that if player 1 has the option of going to a node whose value is 1 he’ll take it, 
and so the node from which he’s moving can be said to have the value 1. Similarly player 
2 will try to make a node -1. Using this rule, we can “back up” the tree from the leaves 
evaluating each node as we go. Look at a small portion of the tree: 


(value 1 because player 1 can go 
to L which is 1) 


(has to be 1, because 
it only leads to T) 



2nd player’s move 


-1 1st player’s move 


2nd player’s move 


If you back up this tree to the root, you’ll find the root evaluates to 1. In other words the 
first player can always win! 

What this shows is that Nim isn’t a very interesting game. Indeed, no game of which 
the complete set of moves can be written down is very interesting, because the impli¬ 
cation is that it can be played in a totally automatic way, without any guesswork or 
inspiration. On the other hand, it’s exactly that feature which should make it easy for a 
computer to play! 
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A PROGRAM FOR NIM 


So, how would we go about designing a Nim playing program? Firstly, it’s obvious that 
we need to store the tree: 


NM 


NV 


PTR 


1 

A 

5 


1 


2 

B 

4 


1 


3 

C 

3 


-1 


4 

D 

3 


1 


5 

E 

2 


1 


6 

F 

2 


1 


7 

G 

1 


-1 


8 

H 

2 


-1 


9 

I 

1 


1 


10 

J 

1 


1 


11 

K 

0 


-1 


12 

L 

1 


1 


13 

M 

0 


-1 


14 

N 

0 


-1 


15 

P 

1 


-1 


16 

0 

0 


1 


17 

R 

0 


1 


18 

S 

0 


1 


19 

T 

0 


1 


20 

U 

0 


-1 



2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

0 

15 

16 

17 

0 

18 

0 

0 

0 

19 

0 

0 

0 

0 

0 

20 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 


node 

reference 


number of 
matches 


node 

value 


left 

pointer 


right 

pointer 


We could set this up with a series of input statements inside a loop, or we could “grow” 
the tree in a similar way to that in which we grew the family tree. Either way, we’ll 
assume that it’s available in the form shown. 

From here on, the problem’s easy. At each stage, the computer has two possible 
moves, given by the PTR values in the current row. It simply chooses one which leads to 
a “1” in the node value array. So to start with, we have to initiate a row pointer to the 
root of the tree, display the number of matches and inform the human player that it’s the 
computer’s go (after all, we want the computer to win, don’t we?): 
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1000 LETR=1 

1010 PRINT “THERE ARE NM (R); “□ MATCHES ON THE TABLE. 

1020 PRINT “IT’S MY GO!” 






Notice that I’ve written NM (R) in line 1010 rather than just “5” because this will enable 
us to use the same statement next time around. 

Now to calculate the computer’s move: 

1030 F0RC=1T02 

1040 IF NV (PTR (R. C)) = 1 THEN GOTO 1060 

1050 NEXTC 

1060 LETR = PTR(R,C) 

1070 PRINT “THERE ARE NM (R); “□ MATCHES ON THE TABLE.” 

The loop (1030-1050) looks for a pointer in the current row which points to an NV value 
of 1. When it finds one it updates the current row to this value. There’s no real need for a 
loop, since there are only two columns (i.e. two possible moves) to consider. But using 
one means that this form of routine will work for more complicated games where there 
are dozens of possible moves and correspondingly many columns. We only have to 
change the “2” in line 1030 to however many columns there are. Note also that we only 
need to find the first “1” in NV. After all, any “1” leads to a win. 

Now we allow the human player a turn: 

1080 PRINT “YOUR TURN NOW ” 

1090 PRINT “HOW MANY MATCHES DO YOU WANT TO PICK UP?” 
1100 INPUT HM 

1110 IFHM>0ANDHM<3THENGOTO1140 
1120 PRINT “NO CHEATING” 

1130 GOTO 1090 

1140 LET R = PTR (R, HM) 

Now to see if we’ve won yet, and if not, to play again: 

1150 IF NM (R) > 0 THEN GOTO 1010 
1160 PRINT “I’VE WON AGAIN!” 

If we want to be generous, we could allow the user to go first every other game, by 
passing control to the “computer move” and “human move” routines in the opposite 
order. That would mean including lines in the move routine to see if the human player 
has won, and treating the two “play” routines as separate subroutines rather than in-line 
code. If there’s a variable called G which counts the number of games played, and the 
two routines begin at 1020 and 1080, as they do here, the calling program could look 
something like: 

500 LETG = 0 

510 GOSUB(1020+120*(G/2-INT(G/2))) 

520 GOSUB (1080 - 120 ♦ (G/2 - INT (G/2))) 

530 LETG = G + 1 
540 GOTO 510 

(don’t forget to terminate the two “play” routines with RETURNs). 

There are various other “cosmetic” modifications to be made (at the moment it 
displays: THERE ARE 1 MATCHES ON THE TABLE, for example), but I’m more 
concerned with another problem: 
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MAKING THE COMPUTER DO THE WORK 


So far, we’ve assumed that the arrays have to be set up manually, in one way or another. 
But do they? After all, we set up the tree, and hence the arrays, from a knowledge of the 
rules of the game, and nothing else. Couldn’t we give the computer the rules and get it to 
generate the array values in a similar way? 

Let’s give it a whirl. The NM array shouldn’t be difhcult; we just start with 5 in row 1 
and use the rules to subtract 1 or 2 from this at each stage. The PTR array will have to link 
these values, and so far we have (without ever actually saying so) adopted the convention 
that the rule “Remove one match” is handled by the first column (rule 1) and the rule 
“Remove two matches” is handled by the second (rule 2). So we’ll stick to that. Of 
course, the NV array will have to wait until we’ve grown the tree, because we need to 
“back up” to get the node values. 

Assuming the arrays are already dimensioned, we can start with: 


90 

LETR= 1 

[first row] 

100 

LETNM(1) = 5 

[set the root] 

110 

LET CP = 2 

[set the “current pointer” to the first 



free row] 

120 

LETNM(CP) = NM(R)- 1 

[rule 1] 

130 

LET PTR (R, 1) = CP 

[link the pointer for rule 1] 

140 

LET CP = CP + 1 

[update 1st free row] 

150 

LET NM (CP) = NM (R) - 2 

[rule 2] 

160 

LET PTR (R, 2) = CP 

[link the pointer for rule 2] 

170 

LET CP = CP+1 

[update 1st free row] 

180 

LETR = R-hl 

[go to next node] 


Now we would like to go back to line 120, of course, to deal with the next node, but we 
need to avoid getting into an endless loop. We could cheat by remembering that there 
are twenty rows in the arrays, and branch out of the loop when we’ve dealt with all 
twenty; but bear in mind that we’re trying to use this game to develop techniques which 
will still be applicable in more complex situations, when probably we won’t know how 
many nodes there are in the tree. 

Actually, there’s an implicit rule we haven’t used yet; namely, that you can’t pick up a 
match which isn’t there. So when matches are subtracted at lines 120 and 150, we ought 
to test to see that NM (CP) does not go negative. If it becomes zero, that implies that 
we’ve reached a leaf. Maybe we can use this to get out of the loop. If we insert: 

115 IF NM (R) - 1 < 0 THEN GOTO 180 

145 IF NM (R) - 2 < 0 THEN GOTO 180 
the “negative match” problem goes away. 

Now let’s think about the way the pointers, R and CP, behave. CP hares off at twice 
the rate of R to begin with, since it’s updated twice every loop to R’s once. When the 
leaves start to be reached, CP slows down and eventually stops at 20, because the tests at 
lines 115 and 145 cause jumps around the “CP update” lines. All this time, R is plodding 
along, tortoise-like, at one update per loop. When it catches up with CP, we know there 
have been no forward entries past this row. So all we need is to test if R = CP yet: 

190 IF R< CP THEN GOTO 115 

Now we’re left with generating the NV array values. Obviously we have to start at the 
leaves. We can find them easily enough, since the NM value at a leaf is zero. But in order 
to give the node a value we have to know whose turn it was. 



Let’s set up another array called WPM (which player to move) whose values wHl be set 
to 1 or 2 according to whether player 1 or player 2 is about to move. Here it is, added to 
the previous table. 


NM NV 


PTR WPM 


y 1 /\ 


5 


1 


4 


1 


3 


-1 


3 


1 


2 


1 


2 


1 


1 


-1 


2 


-1 


1 


1 


1 


1 


0 


-1 


1 


1 


0 


-1 


0 


-1 


1 


-1 


0 


1 


0 


1 


0 


1 


0 


1 


0 


-1 



2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

0 

15 

16 

17 

0 

18 

0 

0 

0 

19 

0 

0 

0 

0 

0 

20 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 


node number of node 

reference matches value 


left right which player 

pointer pointer to move 


So in row 1, the WPM value is 1. Now, the rest of the WPM array is a bit puzzling, 
because there are varying numbers of Is and 2s in each block. In an ideal world they 
would simply double each time: 1, 2, 4, 8 and so on, because there are two branches 
leaving every node. They don’t of course, because some branches would lead to illegal 
moves. So we need a limit on the number of rows we examine with each loop. Initially, 
the first and last entries in WPM are at row 1 so: 

210 LETFST=1 
220 LETLST=1 


To start with, player 1 is making a move so: 
230 LET PLAYER =1 
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Now we want to change the player: 

240 LET PLAYER = (2 AND (PLAYER = 1)) + (1 AND (PLAYER = 2)) 

That’s a sneaky piece of code which will swap PLAYER from 1 to 2 and vice versa. It 
works because the value of a condition is 1 if the condition is true and zero otherwise. So 
one of the parts of the expression disappears and the other is, if you like, multiplied by 1. 
Now, we’ll loop from FST to LST counting the entries in WPM as we go: 

250 LET ENTRIES = 0 
260 FOR R = FST TO LST 

270 IF PTR (R, 1) = 0 THEN GOTO 330 [this branch doesn’t lead anywhere!] 
280 LETWPM (PTR (R,l)) = PLAYER 
290 LET ENTRIES = ENTRIES + 1 

300 IF PTR (R, 2) = 0 THEN GOTO 330 [neither does this one] 

310 LET WPM (PTR (R, 2)) = PLAYER 
320 LET ENTRIES = ENTRIES + 1 
330 NEXTR 

Now look at the next block: 

340 LETFST=LST+1 
350 LET LST = FST + ENTRIES - 1 
and see if we’re over the end of the array yet: 

360 IF FST < CP THEN GOTO 240 

EVALUATING THE MOVES 

Now we can set the NV values for the leaves: 

370 FORR=1TO20 

380 IF NM(R)>0 THEN GOTO 410 

390 IF WPM (R) = 1 THEN LET NV (R) = 1 [here only for a leaf] 

400 IFWPM(R) = 2THENLETNV(R) = - 1 
410 NEXTR 

Next we search backwards through the tree, linking the node values. There are three 
situations to consider: 

1. There’s only one branch, so we can just pass the value back. 

2. There are two branches, and the search finds the left link. 

3. There are two branches, and the search finds the right link. 

In the last two cases, the code is going to be several lines long, testing which pointer points 
to the maximum node value, and whether we want to pass back the minimum or maximum 
value, depending on who is about to play. So we’ll put it in a subroutine starting at line 
8000. The code is: 

420 FOR R = 20TO2 STEP - 1 
430 FORRP=1TO20 
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440 IF PTR (RP, 1) = R AND PTR (R, 2) = 0 THEN NV (RP) = NV (R) 

450 IFPTR(RP, 1) = RAND PTR (RP, 2)0 0 THEN GOSUB 8000 
460 IF PTR (RP, 2) = R THEN GOSUB 8000 
470 NEXTRP 
480 NEXTR 

Notice that, to make the code simple, all twenty rows are always searched in the inside 
loop. Of course, they don’t need to be, because there’s only one reference to a given 
pointer in the PTR array. So the code is inefficient, but tidy. 

Now for the subroutine: let’s make a table showing all the possible combinations of node 
values being pointed to, and show also what each player would want as a backed-up node 
value: 


Left pointer 
node value 

Right pointer 
node value 

Player 1 

Player 2 

-1 

-1 

-1 

-1 

-1 

1 

1 

-1 

1 

-1 

1 

-1 

1 

1 

1 

1 


In the first and last cases, there is no choice in the backed up value, since both branches 
lead to the same number. 

What we ought to do is determine in each case what the maximum and minimum value 
is, but this seems a bit like overkill for just two branches. (If there were more, we would 
have to do this.) Suppose we add the two node values in each line: 

-2 

0 

0 

2 


Now, only when this value is —2 is a “—1” forced to back up and only when it’s 2 is a “1” 
forced to back up: 


8000 

8010 

LET TV = NV (PTR (RP, 1))+ NV 
(PTR (RP, 2)) 

IF WPM (RP) = 2 THEN GOTO 8050 

[add the node values] 

8020 

LETNV(RP) = 1 

[for player 1 assume node 

8030 

8010 

IFTV < 0THEN LETNV (RP) = -1 

RETURN 

[if it can’t be, set it to -1] 

8050 

LETNV(RP) = -1 

[for player 2, assume node 

8060 

8070 

IFTV > 0THEN LET NV (RP) = 1 

RETURN 

[if it can’t be, set it to 1] 
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OTHER GAMES? 


And that’s it! A computer program which works out its own strategy! OK, the code is less 
than elegant in places; and here and there I’ve made use of features of this particular game, 
rather than making things totally general; but I was concerned with making it as easy as 
possible to follow the code. (Anyway that’s my story.) It shouldn’t be difficult to apply 
these principles to the design of a noughts-and-crosses-playing-program, for instance. 
(Remember though, that in this case it’s possible for the game to be drawn so node values 
of zero will appear.) 

More complicated games have a serious problem, however. The trees get colossal. Take 
chess for example. The first player has a choice of 20 moves to start with. (Two moves with 
each of eight pawns and two moves with each knight). The second player has exactly the 
same options from each of the 20 nodes just generated, so there are 421 nodes (including 
the root) after just one move each! 

The solution is not to grow the whole tree—it simply wouldn’t be possible, however 
large a machine you had—but to restrict it to, say, five moves ahead. Of course, that means 
it has to be regrown every move, and it also means that there may not be any leaves in the 
region we’re looking at. That’s a problem, because our whole technique has depended on 
setting the leaf values and backing up the tree. 

What we have to do is to give values to the terminal nodes in the portion of the tree we 
have stored, according to some set of rules. At the simplest level we score high if we win 
material and low if we lose pieces. Then we add some “fine tuning’’. For example, deduct 
points if our king is unprotected, add them on if our queen controls the centre files. How 
many points to allot for a particular feature is pretty much a matter of intelligent guesswork 
to start with. Scoring will become modified with experience of how well, or badly, the 
program plays. 

I don’t recommend that you leap into action and write a chess-playing program, but 
there are a number of simpler games which are relatively easy to program and at which 
your 1000 can be made to play a surprisingly mean game. Connect-4 and Othello spring to 
mind. But BASIC versions are pretty slow: read the Machine Code section if you want to 
speed up the action—and then prepare for a long job of programming! 
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TREES AND INTELLIGENCE 

To the outside user, our Nim or Othello player will appear to play pretty sensibly. It will 
avoid obvious traps, go for winning moves and, in general, will not make aimless plays. 
That’s what a human player would do. So, does the program exhibit intelligence? 

Well, it depends on what you mean by intelligence. If you mean the ability to model 
human behaviour in some way (however restricted the field), then the program does do 
that. If you mean the ability to solve problems which are completely new to the machine, 
then of course, it can t. But can anybody? Don’t we all need some set of rules to work 
fi-om—some prior knowledge? So maybe the real problem is to devise ways of giving the 
machine sets of rules (a model of the relevant aspect of the world, if you like) in as 
convenient a way as possible. 

The family tree example is, if you think about it, a simple case of rule giving. After all, a 
statement like: Martha and Tom are the parents of Jim” is not, logically, very different 
from a doctor making a diagnosis saying “A high temperature and spots indicate measles”. 
All we’ve done is replace “Martha” with “a high temperature”, “Tom” with “spots” and 
“Jim” with “measles”. It’s possible to design a system which allows a consultant surgeon, 
for instance, to tell it about symptoms, diagnoses and so on, and which stores all this 
information in tree-like structures. It can then search the tree to make its own diagnoses 
when sets of symptoms are given to it. It may even “discover” simplified sets of rules 
leading to a particular conclusion. 

So trees are pretty interesting structures, although handling them can get a little hairy at 
times. Usually, though, splitting the program down into manageable lumps (as we did in 
the Nim program), and careful dry running, will allow you to create interesting and useful 
routines. 
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structured 

Programming 




As well as structuring your data, you should also structure the program. Essentially this 
means writing it as a series of linked subroutines—which can be debugged and tested 
separately, and then strung together, safe in the knowledge that they work. You can 
name the subroutines in REM statements if you want, to make the listings easier to 
follow. 

More elusive than structure is style. Each progranuner has his own; and my favourite 
trick may not be to your taste. If you compare FRENCH COUNTDOWN and 
ZEDTEXT you’ll certainly notice the difference in style—but you may not prefer the 
same style as somebody else. Style is partly clarity and efficiency, and partly good 
organization; but there’s something else, which is hard to pin down. 

Rather than lecture to you about structure and style. I’ve written out three case- 
histories of the design of longish 16K programs (in BASIC). One is a text-editor, one a 
statistical simulation of supermarket checkouts, and one is an educational program to 
help teach French (kindly provided by Eric Deeson of the Educational ZX User’s 
Group, EZUG). If you don’t want to wade through the description, just copy out all the 
lines in order, as they app>ear. But I’d rather you took them routine by routine, which is 
one reason why no complete listing is given on its own. 
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A versatile, albeit slow, text-editor, which gives insight into 
program structure, word-processors, and the way 
your BASIC interpreter works. 


8 Ze(lt0ct 


You hear an awful lot these days about word-processors or text-editors: programs that 
turn a microcomputer into an intelligent typewriter able to edit and manipulate a written 
text. The 1000 ’s facilities for on-screen editing of programs (line cursor , character 
cursor [2 ^ RUBOUT, EDIT, and insertion of new characters from the keyboard) 
amount to a rudimentary text-editor. Some commercial systems are immensely compli¬ 
cated, and can paginate, justify, and index text automatically. 

The 1000 won’t act as a practical text-editor, at least not until someone produces a 
gadget to link it up to a fancy printer. But, by seeing how a text-editor for the 1000 can 
be designed, you can begin to appreciate just what is involved in a commercial system. In 
addition, it’s an excellent example of structured programming. 

This case-history is the tale of ZEDTEXT and how it came about. 



ZEDTEXT title page. 

CHOOSING A DATA STRUCTURE 

A text-editor must accept textual input, and process it in various ways. Before starting on 
the program to do this, we must first work out the most suitable structure for the 
data—the text itself. But before structuring the data, we have to consider what we intend 
to do with it. Vicious circle? No, because we can think pretty loosely at first, and write a 
few experimental programs to test our hunches. 





One important feature is that we should be ooble to delete mistakes like that one, to 
produce a clean text: that is, we should be able to correct mistakes. Another is that we 
should be able to append text (or insert it in the middle like this) to existing text, just as 
this sentence is appended to the previous one. A third is that we should be able to search 
a text to find the first (second, third,. . .) occurrence of a given sequence of symbols— 
just as the italics find the first occurrence of “search” on this page (and the quotes find 
the second!). Wed also like to be able to repeat such operations a specified number of 
times (e.g. “Find the first occurrence of ‘FRED’ and replace it by ‘JIM’; repeat 73 
times”, which replaces every occurrence of FRED by JIM for the first 73 occasions 
FRED appears). Numerous other features would be desirable—the ability to remember 
a segment of text and copy it into a chosen place, the ability to save the results of all this 
on tape, and so on—but the above will suffice for deciding on a data structure. 

So let’s think about the possibilities. 

(a) Think of the text as a one-dimensional array T$ of single characters: 


T 

H 

I 

S 

□ 

I 

S 

□ 

A 

□ 

T 

E 

X 

T ... 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 ... 


(To save space I’ve drawn it horizontally.) The main problem with this is that to insert 
material in T$ we need to shift lots of characters up several spaces, using code like: 

1000 FOR K = TOP TO BOTTOM STEP - 1 
1010 LET T$ (K) = T$ (K - 92) 

1020 NEXTK 

(say). We start at the top and work downwards, of course, so as not to erase sections of 
text not yet moved. 

This looks as if it would run rather slowly on a text of, say, 3000 characters: otherwise it 
has the advantages of simplicity. 

(b) Linked lists. Arrange the text in a list, with pointers to the next character. 


Number 

Character 

Pointer 

1 

T 

2 

2 

H 

3 

3 

I 

4 

4 

S 

5 

5 

□ 

6 

6 

I 

7 


Modifications of the kind “insert” or “delete” are now very easy. For example, to 
change the text to 

THISDISDNOTnADTEXT... 

all we do is add to the end of the list 
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15 

N 

16 

16 

O 

17 

17 

T 

18 

18 

□ 

19 


and then modify two pointers to get the characters in sequence: 


8 

□ 

11 

18 

□ 

9 


Deletions are equally easy: you just change one pointer to reroute past existing text. 
(One minor problem: the deleted text is still “there” in the sense that it’s taking up 
memory space—it’s just that you won’t find it by tracking through the list following 
pointers, because nothing points into it. If memory is short, it’s a nuisance wasting it in 
this way. There’s a good way out, though: put up some kind of flag in the deleted entries, 
and every so often do a “garbage collection run” which goes through the list re¬ 
numbering everything and getting rid of the flagged entries. But such a garbage 
collection will be slow to operate, so the best time to do it is when you get fed up and go 
off to make some coffee. Moral: don’t collect garbage until the memory is close to full.) 

(c) A variant on (b): use linked lists of words. Now you’ll have a genuine word- 
processor, but it won’t be very good at handling symbolic text, e.g. program listings. 

The above discussion is rather theoretical. In practice, which of these three structures 
you use depends heavily on the particular architecture of the machine you are using. So 
let’s see how the 1000 copes. 

(c) turns out to be a bit awkward, because of that Procrustean assignment that the 
Manual goes on about: string arrays always have a fixed length of word. This means that 
you have to dimension the array to fit in the longest word likely to be used, say 

DIM T$ (500,20) 

for 20-character words. But now our sample text above goes in as 


1 


2 

2 

isonnnnnDaDnnDnnnnnna 

3 

3 

AnnnnnnDnnnnnnnnnDan 

4 

4 

TEXT □□□□□□□□□□□□□□□□ 

5 


which wastes acres of memory... Now, by being clever, you could doubtless take care of 
some of this; but it all takes time and program space, and it smells complicated. 

So ditch that one. 

Linked lists (b) look very attractive, but there’s a hidden snag. The pointers take up 6 
bytes each, because of the floating-point representation in the 1000 . (If you’ve got an 
old-fashioned ZX80, which only does integer BASIC, you’re laughing, because two 
bytes will do the job admirably. Moral: don’t despise the ZX80—you always pay a price 
for extra sophistication.) So each character in the text takes up 7 bytes instead of 1, 
reducing the size of the text you can handle. 

One way out is to code the pointer in binary (or hex) using two characters: 

xy means 256 * CODE (x) + CODE (y) 

Now the pointer takes 2 bytes per entry—3 altogether. That’s given us 7/3 of the 
capacity. The main price we pay is the time spent encoding or decoding the pointers, an 
operation we will have to do rather often as we track through the list. 

In my ignorance, I actually wrote most of a text-editor using this linked list structure 







(b). It was a bit slow, but it did the job. A lot of commercial editors do in fact use linked 
lists: for extra speed they’re usually written in machine code—a daunting task. But on 
the 1000 there’s a better way, because the 1000 processes strings very efficiently. For 
example, it will accept strings of arbitrary length (subject to memory size). There are 
very few micros that will do this (a limit of 200-250 characters is common) and indeed 
many mainframe computers do not have this facility in their standard compilers for 
languages such as BASIC or ALGOL. 

As a result, we can use option (a) above, with a difference. As it stands, it’s a bit 
clumsy. But the 1000 treats a vector of single characters as if it were a single string', and 
the ability to refer to specific characters in the string is built into the BASIC interpreter. 
That is, if we set 

LETTS = “THISDISDADTEXT” 

then substring slices allow us to ask for, say, the 7th character. For instance, 

T$ (7) = “S” 

So T$ is effectively the same as the vector 
(T$(1),T$(2),...,T$(N)) 

where N is its length. Better still, we can also assign substrings: if we type in 

10 LETT$(3) = “A” 

20 LETT$(4) = ‘T” 

30 PRINT T$ 
we get 

THATniSDADTEXT 
as result. 

Thus we have the rather alarming option: 

(d) Store the text as a single (long!) string T$. 

Why alarming? Well, we don’t usually think of the 1000 having to deal with strings 
3000 characters long. 

But in fact it rather likes them. 

I did some experiments, with strings of length 600 or so. The first discovery was that 
PRINT T$ will display a screenful of characters in about a second or less—about a factor 
of IW better than can be done using linked lists (b). 

The next: inserting a piece of text (with all that shifting of characters) works even 
faster. For instance 

LET T$ = T$ (1 TO 73) + “NEW TEXT” + T$ (74 TO 600) 
takes next to no time; and so does deletion: 

LETTS = T$ (1 TO43) T$ (92TO 600) 

It’s even better than that, because you can save a few bytes by omitting the start and 
finish of the string, like this: 

LET T$ = T$ (TO 43) + T$ (92 TO) 

The 1000 ’s BASIC interpreter manages to convert these string-shifting instructions into 
efficient machine code, hence the speed. For an idea on the kind of code, see pages 153 
and 182. 

So, after all that, it transpires that there are very good reasons to select a particularly 
simple 

Data Structure: The text will be stored as a single string T$ of unspecified length. 

As it happens, this has expository advantages too: it’s much easier to see how the 
various subroutines work if this rather transparent data structure is used. 







COMMAND FORMAT 

The next step is to decide on a format for the text-editing commands that we wish to 
input. In effect, we are going to write a (small) computer language, which the program 
will decode and act upon (interpret). Just as the built-in ROM interpreter in the 1000 
decodes and interprets BASIC language instructions, turning them into machine code, 
so our program will decode ZEDTEXT commands into BASIC (which the 1000 will 
then turn into machine code—makes you wonder just what really goes on inside its little 
silicon head, doesn’t it!). 

There is room for a lot of flexibility here. After some thought I settled on the following 
format for each instruction: 

[number] [single letter] [string] 

to mean (roughly) perform on the given string an operation coded by the letter, and do 
this the indicated number of times. For instance 

5AFRED 

would mean “add to the text five copies of the string FRED’’. Thus CAT becomes 
CATFREDFREDFREDFREDFRED, and so on. The advantage of such an instruction 
format is that it’s easy to decode: all you need to do is to scan along it looking for the first 
non-numerical character, the code letter; then the number part is everything before that; 
the text part everything after. 

Rather than input a single command at a time, it would be nice to input a whole 
sequence of commands. To separate the individual commands I needed to choose some 
little-used character to act as a delimiter. For this program I chose (shifted Q): you 
can easily change this if you prefer something else. It is set in bold type for clarity. So I 
was envisaging input commands something like: 

5AFRED“”2FRE“”7D“”2ADOG 


meaning ''append 5 copies of FRED, find 2nd occurrence of RE; delete next 7 charac¬ 
ters; append 2 copies of DOG”. The exact details will come later; the results of course 
depend on just how the subroutines interpret their commands. 

The decoding routine for this “macro-language” must therefore do the following: 

1. Scan the string of characters input and locate the first occurrence of the 
delimiter 

2. Break up the first command into [number] [letter] [string]. 

3. Use the [letter] code to call a subroutine which implements the relevant 
command, using the given [string], the required [number] of times. 

4. Find the next occurrence of and repeat the process. 

5. Repeat this until the end of the input command is reached. 




Here’s one way to do it. 


1000 

1010 

1020 

1030 

1040 

1050 

1060 

1070 

1080 


1090 

1100 

1110 

1120 

1130 

1140 

1150 

1160 

1180 

1190 

1200 

1210 

1220 

1230 


REM IMACRO DECODE I 
LET D = 0 


LETI = 1 
INPUT M$ 

LETL = LENM$ 

IF M$ (L) < > THEN LET M$ 

= M$ + 

LETL = LENM$ 

LET A = CODE M$ (I) 

IF A >=38 AND A <=63 

THEN GOTO 1110 

LETI = I + 1 

GOTO 1070 

LET 10 = I 

LETK$ = M$(I) 

IF 10 = D + 1 THEN LET N = 0 
IFI0OD + 1THENLETN = 
VALM$(D+ 1TOI0- 1) 


3- read command 
— tidy 


look for command 
mnemonic letter 


3 - 


set K$ to the 
mnemonic 
read number 
preceding K$ 


LETI=I+1 

IF M$ (I) < > THEN GOTO 1150 
LETD = I 

LET W$ = M$ (10 + 1 TO D - 1) 
GOSUB F (CODE K$ - 37) 

IF I = L THEN GOTO 1000 
LETI = I + 1 
GOTO 1070 


I 

3 - 

Zh 

> 


find next 
delimiter 

read string between 
K$ and delimiter 
carry out command 
finish 

decode next 
command 


To see how this works, try it out (“dry-running”, see Timex/Sinclair 1000) when M$ is 
5AFRED ""2FRE"^^7D"'^ADOG. The first thing it does is stick another delimiter 
on the end, if there wasn’t one already. Then it tracks along M$ looking for the first 
letter, and finds A. It sets K$ = “A”. T^e stuff in front of the A is decoded as a number 
and set equal to N, so N = 5. Then it tracks along further looking for the delimiter 
Everything between K$ and this is lumped into a string W$, so here W$ = “FRED”. 

Now armed with the data N = 5, W$ = “FRED”, it does a GOSUB to the routine at 
F (1) corresponding to the mnemonic A. After that it repeats the search from the new 
delimiter position on, carries out the new command, and continues until it reaches the 
end of M$. Then it gets ready for the next sequence of instructions. 
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So, tabulating the results in an obvious way, the upshot is: 


Mnemonic 

letter, K$ 

Number 

N 

String 

W$ 

Operation 

A 

5 

FRED 

GOSUB F (1) [append 5 copies of FRED] 

F 

2 

RE 

GOSUB F (6) [find 2nd RE] 

D 

7 


GOSUB F (4) [delete next 7 characters] 

A 

2 

DOG 

GOSUB F (1) [append 2 copies of DOG] 


So, assuming we get those subroutines written, if we started with T$ = (empty) we 
would get, in turn: 

FREDFREDFREDFREDFRED 

fredfeedfredfredfred 

FREDEFREDFRED 

FREDFDOGDOQFREDFRED 

where the underline indicates the “current” position in text (see below for details). 
Anyway, it ought to work ... 


CHOICE OF COMMANDS 

I decided on the following possibilities for K$: 

A append extra text 
C move the cursor 
D delete 

F find a given piece of text 
J justify 
K list the program 

L list the program (yes, again! I kept hitting it by mistake) 

M display how much memory is available 
P print a “page” of text 

R reset all variables 
S save on tape, including current text 
T set up a test text 

X execute preceding commands a given number of times 
Z stop 

Of these, K, L, M, T and Z were introduced for convenience during the writing—I kept 
hitting K, for “list”, but since I was inputting a string, the machine refused to obey that 
instruction. T saves a lot of time testing, and is useful for demonstration purposes. 

What happened in practice was that I slowly built up the subroutines for these 
commands, fitting them in at convenient line numbers. By the time the whole program 
was written and debugged, the numbering had got pretty random and the line numbers 
were all over the place. At that stage I decided to tidy it all up: but at least I then knew 
how many lines each subroutine would need. (A line renumbering routine would do a lot 
of this job, but it’s not a universal panacea.) Of course, when you tidy programs you 
make changes and mistakes, and need to debug again, but it’s worth taking the trouble if 
you intend to use the program often, or want to modify it later. Moral: when the program 
works, you haven’t necessarily finished. 
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Putting the subroutines in alphabetical order (by “mnemonic” K$), and allowing for 
their lengths, leads to an initialization routine for the array F, like this: 

10 DIM F (26) 

20 LETF(1) = 2000 
30 LET F (3) = 2200 
40 LET F (4) = 2500 
50 LET F (6) = 2600 
60 LET F (10) = 2800 
70 LETF(11) = 3000 
80 LET F (12) = 3000 
90 LET F (13) = 3100 
100 LET F (16) = 3300 
110 LET F (18) = 3500 
120 LET F (19) = 3600 
130 LET F (20) = 3800 
140 LET F (24) = 3900 
150 LET F (26) = 4000 

For example, line 100 means that K$ = P gives a branch to F (CODE K$ - 37) = F (53 - 
37) = F (16) = 3300, in the “operating” line 1200 of the MACRO DECODE routine. 
That is, the PRINT subroutine should begin at line 3300. 

Of course, you don’t actually need to initialize F this way: once these values are stored 
in memory, they get SAVEd without change; so you can put them in by direct 
commands, or by writing a little initialization routine which you then erase, or by 
whatever method you fancy. But remember not to use RUN if you do it that way! Unless 
memory’s getting short, it doesn’t matter much. 


THE MOVING CURSOR WRITES... 

If we’re going to append or delete text, we’ll need to know where to do these things. 
That’s what the cursor command “C” is for: it selects a “current” position in the text. For 
visual display, I decided to use a flashing cursor, changing the relevant character to 
inverse video and back a few times, and ending on inverse video for clarity. (The 
program will nevertheless handle inverse video in a text.) So the “C” subroutine, at F (3) 
= 2200, comes out like this: 

Initialize: 


200 LET T$ = “” [empty string] 
210 LET Cl = 0 

Now the actual routine: 


2200 

2210 

2220 

2230 

2240 


REM [CURSOR] 

IF W$ = “0” THEN GOTO 2360 

LETCI = CH-N “I 

IF Cl > LEN T$ THEN LET Cl = LEN T$ 

IF Cl < = 0 THEN GOTO 2360 




2250 

LET PN = INT ((Cl - l)/640) 




2260 

LETCP = CI-640*PN 



find print 

2270 

LET LN = INT ((CP - l)/32) 



position 

2280 

LETCN = CP-32*LN- 1 




2290 

2300 

LET J = CODE T$ (Cl) + 128 

IF J >= 256 THEN LET J = J - 256 

— 

invert video 

2310 

FORY= 1TO10 




2320 

PRINT AT LN, CN; T$ (Cl) 


_ 

flash cursor 

2330 

PRINT AT LN, CN; CHR$ J 




2340 

NEXTY 



1 

2350 

RETURN 




2360 

LET Cl = 0 




2370 

RETURN 





In this routine Cl denotes the cursor position in the text T$, so that T$ (Cl) is the 
“current” character in the text. The macro command nCjunk determines a number N = 
n and the routine advances the cursor index Cl to Cl + N. If this number is not in a 
suitable range it is trimmed to avoid program crashes (crashproofing). The new value of 
Cl is processed to determine the print position of the character T$ (Cl) on the screen, 
assuming text is displayed in “pages” of 640 characters (20 lines—the other two are kept 
spare). A flashing cursor is displayed, ending on the inverse video character for clarity. 

For instance, suppose the current text is T$ = 

THEDMOVINGDCURSORDWRITES 

and the cursor is at Cl = 7 as shown. Then the command 5C (followed by any string, or 
none) will advance the cursor to Cl = Cl + 5 = 7 + 5 = 12 and display a flashing C at this 
position: 


THEDMOVINGDCURSORDWRITES 

T 

flash 


The number N can be negative or zero, so we can backspace the cursor or leave it where 
it is. This last option may sound pointless, but it is used in the PRINT routine, for 
example, because that is actually “print, and display cursor” and we don’t want the 
cursor to move. 

However, it is important to be able to reset the cursor to the start of the text; and line 
2210 copes with this, by making use of the fact that W$ is not normally relevant to a 
cursor instruction, so can be used to carry extra information. Here C0 (or nC0 for any 
number n) resets the cursor to the front. Another useful addition might be 

2215 IF W$ = “1” THEN GOTO 2380 
2380 LET Cl = LENTS 
2390 RETURN 

This takes Cl to the end of text (ready to add more). Throughout the program. Cl is kept 
between 0 and LEN T$ to avoid problems with the range of subscripts; and the case Cl = 
0 usually requires special treatment. 
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DISPLAY 


So far so go<^; but we haven’t got anything on the screen to work with. Let’s write that 
PRINT routine, at F (16) 3300. The idea is to use the top 20 lines of screen (saving a 

couple at the bottom for, say, page numbers or helpful messages), so we get “pages” of 
640 characters each. With text up to (about) 3000 characters, that gives 5 or so pages. 

The command nP obviously ought to mean “print out the nth page”. But what about 
0P or just P (which is interpreted as 0P)? It would be nice if this meant “print out the 
current page . And that means we need to remember which page we’re on. So we’ll have 
CPN as the “current page number”. We’d best initialize it: 

220 LET CPN =1 
Now for the subroutine: 


3300 

3310 

3320 

3330 

3340 

3350 

3360 

3370 

3375 

3380 

3390 


REM [PRINT I 
CLS 


IFN = 0THEN LETN = CPN 
LET CPN = N 
LETH = 640*N 

IF LEN T$ < H THEN LET H = LEN T$ 
PRINT T$ (640 * N - 639 TO H) 

PRINT AT 21,0; “PAGED”; CPN 

LETN = 0 

GOSUB2200 

RETURN 


Now we’ve got CPN, it’s much better if C0 sets the cursor to the start of the current 
page. The way to do this is to change the CURSOR routine: 

2360 LET Cl = 640* (CPN - 1) 

There’s another snag to take care of too. Namely, if the variable PN in the CURSOR 
routine is not CPN — 1, then the cursor gets printed out even though we’re on the wrong 
page! To avoid this, the instruction 

2255 IF PN<> CPN - 1 THEN RETURN 
needs to be added. 

As you can see, adding new subroutines that use old ones can sometimes mean a 
rethink on the old ones. 


APPEND 


One more subroutine, and we’re in a position to try the program out. It’s no use havine 
CURSOR and PRINT but no text! 

We want things like 5AFRED to mean “append 5 copies of FRED”, that is, insert 
FREDFREDFREDFREDFRED into T$. But where? The best place seems to be 
between T$(CI) and T$(CI +1), that is, imme<ftate(ya^er//ie cursor. (This is why Cl = 0 
to LEN T$ is the sensible range: we need to get at both ends.) Where do we want the 
cursor to go after appending? On the end of the new stuff, probably; ready to append 
more, or move on to pastures new. 




2000 

REM 1 APPEND 1 



2010 

IFN = 0THENLETN= 1 



2020 

LETU$ = 

— 


2030 

FORQ= ITON 


make N copies 

2040 

LETU$ = U$ +W$ 


ofW$ 

2050 

NEXTQ 



2060 

IF Cl = 0 THEN GOTO 2110 

— 


2070 

IF Cl = LEN T$ THEN GOTO 2130 



2080 

IF Cl > 0 AND Cl < LEN T$ THEN LET 


— append this 


T$ = T$ (TO Cl) + U$ + T$ (Cl + 1 TO) 



2090 

LETCI = CI + LENU$ 

ID— update cursor 

2100 

RETURN 



2110 

LETT$ = U$ + T$ 



2120 

GOTO 2090 



2130 

LETTS = T$ + U$ 



2140 

GOTO 2090 




so FAR, SO GOOD? 

Now we re ready for a test run. Press RUN; it wants an input. For a start, try 
5AFREDD“”P 

which should print out on the screen 

FREDaFREDDFREDDFREDDFREDD 

T 

and flash the final space as cursor. It does, so we’re not doing too badly; and there’s 
PAGE 1 at the bottom. 

Now try C 5C 2ACATn P and see if you get 

FREDnCATOCATnFREDnFREDDFREDnFREDD 

T 

with the cursor where the arrow is drawn. Reset cursor (to Cl = 0), shift up 5 (Cl = 5); 
append 2 copies of CATO; print the lot. 

Well if any of our subroutines were wrong, we’d have run into trouble, so it looks 
pretty good, doesn’t it? But, there’s one feature we haven’t checked out; namely, 
whether everything works on pages 2,3,4, and so on. We need a longer text. Type RUN 
(to clear away the junk accumulated so far); then input 

IWAABCDEFGHIJK 

and go and make the coffee. (Actually it only takes 20 seconds, even in SLOW mode.) 
When you come back, T$ ought to be 1100 characters long; just ABCDEFGHIJK 
repeated over and over again. 

OK, now try 

IP 

2P 

3P 

in turn. How are we doing? 


59 




After a test, ending at **; the result of the input command “25y4Cy47’n“”25y4DOGn“”-/(?C“”P”. 

DELETE 

You should be getting a good idea how all this works by now, so I’m going to leave it to 
you to test out each new feature as it’s added; and I’ll try to be more brief. 

Command D will delete N characters, starting at and including the current one; and 
reset Cl to the position immediately before the deleted passage. Why? Because then it’s 
easy to append text in the space where the deleted bit was. For instance, 8D 
AHARRY will delete 8 spaces, stick HARRY into that slot, and close up the gaps. 

im REM IDELETC 

2510 IFN = 0THENLETN= 1 

2520 LETL0 = LENT$ 

2530 IFCI<=1ANDN>=L0 

THEN LET T$ = [empty string] 

2540 IFCI<= 1 ANDN<L0 

THEN LETTS = T$ (N + 1 TO) 

2550 IFCI>1 ANDCI + N-1>=L0 
THEN LETTS = TS (TO Cl - 1) 

2560 IFCI>1 ANDCI + N-1<L0 

THEN LET TS = TS (TO Cl - 1) + TS (Cl + N TO) 

2570 LETN=-1 
2580 GOSUB2200 
2590 RETURN 

SOME COME CHEAP 

The next few options are trivial to program, but useful—especially during writing and 
development. I kept hitting K (“LIST”) or even L, in the hope of getting a listing—of 
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course the machine goes to F of something for which there’s no subroutine, and all sorts 
of things can happen. To avoid much hair-tearing, I eventually added in routines K, L, R 
and Z for LIST, LIST, RUN, STOP. A memory-test M proved useful too. 


3m REM Ik AND LI 
3005 CLS 

3010 IF W$ = “’’THEN LET N = 1 

3015 IF W$ <> ‘ ” THEN LET N = VAL W$ 

3020 LISTN 
3025 RETURN 

3500 REM I RESET I 
3510 RUN 
3520 RETURN 

4000 REM I STOP I 
4010 STOP 

3100 REM I MEMORY I 
3110 CLS 

3120 PRINT AT 5,0; “SPACE FOR TEXT IS 
3130 PRINT PEEK 16386 -I- 256 * PEEK 16387 
- PEEK 16412 - 256 * PEEK 16413; 

3140 PRINT “□B'YTES” 

3150 RETURN 

This last routine makes use of the system variables ERR-SP, marking the bottom of the 
GOSUB stack, and STKEND, the top of the calculator stack. However, the machine 
stack sits in this spare space, so the figure is only an approximation. Still, it will warn you 
if memory is getting tight. 

TEST 

This, again, is most useful during writing and debugging; and you can omit it to save 
space or erase it once the program is working. Use your favourite phrase or saying! 

3800 REM [testI 

3810 LET T$ = “TO SEE A WORLD IN A GRAIN OF SAND 
AND A HEAVEN IN A WILD FLOWER, 

HOLD INFINITY IN THE PALM OF YOUR HAND 
AND ETERNITY IN AN HOUR.” 

3820 RETURN 

FIND 

This command searches the text for the Nth occurrence of a substring W$. So, for 
instance, 3FBUG asks for the 3rd occurrence of BUG. The cursor should be set at the 
beginning of the substring BUG once it is found. That suggests we first search for the first 



character W$ (1) = B, and then do a subsequent check for UG. To save time, this one is 
programmed in FAST mode. 


im REM inNDI 
2610 FAST 

2620 IF T$ = “” THEN GOTO 2780 

2630 IF Cl = 0 THEN GOTO 2636 

2634 IF W$ (1) = T$ (Cl) THEN LET Cl = Cl + T 

2636 IF Cl = 0 THEN LET Cl = 1 

2640 IFN<=0THENLETN= 1 

2650 LETL1 = LENW$ 

2660 LETFC = 0 

2670 IF Cl + LI - 1 > LEN T$ THEN GOTO 2780 
2680 IF T$ (Cl) <>W$(1) THEN GOTO 2700 _ 
2690 IFT$(CITOa + Ll-l) = W$ “ 

THEN GOTO 2720 _ 

2700 LETCI = CI + 1 ~ 

2710 GOTO 2670 

2720 IF FC>= N - 1 THEN GOTO 2750 
2730 LETFC = FC+1 
2735 LET Cl = Cl+ 1 

2740 GOTO 2700 _ 

2750 LETN = 0 H 

2755 SLOW 
2760 GOSUB 2200 

2770 RETURN _ 

2780 SLOW 

2785 PRINT AT 21.0; “NOT FOUND” 

2790 RETURN 


[empty string] 


look for 1st character 


look for the rest 


update counter 


print cursor 


Note that this program looks for the Nth occurrence of W$ after (that is, not including) 
the current cursor position Cl. 


MULTIPLE EXECUTION 


This command—which for simplicity we assume is only used once in a given input 
M$—will mean “do everything before this command N times”. That is, 2FCAT“”3D 
“”ADOG“”7X“” will mean “find the 2nd occurrence of CAT, delete 3 characters (i.e. 
delete CAT), append DOG (i.e. replace CAT by DOG); repeat all this 1 times”. 

What we do is set up a counter XC which gets updated by 1 on meeting the command 
X, until it hits N. Then we reset the counter and continue. Every time X is read, and EC 
has not reached N, we are sent back to the front of M$ in the MACRO DECODE 
routine. 
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3900 

- REM 1 MULTIPLE EXECUTION Xl 


3910 

IFXC = N-10RN<= 1 ~ 

|— finished? 


THEN GOTO 3960 J 

3920 

LETXC = XC+1 “ 

— update counter 

3930 

LETD = 0 n 


3940 

LETI=1 _ 

— reset 

3950 

GOTO 1040 

[yes, GOTO, not RETURN!] 

3960 

LETXC = 0 


3970 

RETURN 


Initialize: 

230 

LETXC = 0 



Actually this routine leaves some GOSUB addresses piled on the machine stack: if 
used a lot, it wastes memory .Try to get round this problem by using a GOTO instead of a 
GOSUB when calling line 3900. 


JUSTIFY 



Justified text: no broken words at right-hand end. 


So far the text is printed without any tidying where it goes over a line. The next 
subroutine “left justifies” the text. 1000 lines, at 32 characters each, are too short for 
right justifying to be worth doing; but you might like to consider what such a routine 
would look like. (It must distribute the necessary extra spaces between words at random 
to make up the right length on each line.) 
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2800 

2810 

2820 

2830 

2835 

2840 

2850 

2860 

2870 

2880 

2890 

2900 

2910 

2920 

2930 

2940 

2950 

2960 


REM I JUSTIFY 
LET Cl = 1 

IF Cl + 31 > LEN T$ THEN RETURN 
LETV$ = T$(CI + 31) 

IF Cl + 32 > LEN T$ THEN RETURN 
IFT$ (Cl +32) = “□’’THEN LETTS = 
T$ (TO Cl + 31) + T$ (Cl + 33 TO) 
LET 12 = 32 

IF V$ (12) = THEN GOTO 2920 

LET 12 = 12- 1 

IF 12 = 0 THEN GOTO 2900 

GOTO 2860 

LET Cl = Cl+ 32 

GOTO 2820 

DIM H$ (32) 

LETH$ = V$(TOI2) 


~1- crashproof 
read line 




tidy next 
line 


find last non-space 
character 


h pad out with spaces 


LET T$ = T$ (TO Cl - 1) + H$ + T$ (Cl + 12 TO)"]-stretch T$ to fit 


LET Cl = Cl+ 32 
GOTO 2820 




next line of text 


SAVE 


The main point with SAVE is that we may want to stop in the middle of an editing job 
and continue later, so we want to save the variable T$. This, of course, is automatic—but 
a start with RUN would wipe it out. The obvious thing is to put a GOTO 1000 after the 
SAVE, so that the program, once loaded, performs the GOTO. Since we’re doing that, 
though, we may as well jazz up the presentation a bit. And... it’s not a bad idea to make 
the SAVE routine user-friendly, with a few checks and reminders. 


3600 

3610 

3620 

3630 

3635 

3640 

3650 

3655 

3660 

3670 

3680 


REM I SAVE I 
CLS 


PRINT “ ISAVE 
PRINT 

PRINT “INPUT PROGRAM 
“”ZEDTEXT“” ’’ 

PRINT “START TAPE ” 
INPUT V$ 


NAME. DEFAULT NAME IS 


IF V$ = “’’ THEN LET V$ = “ZEDTEXT’ 
SAVEV$ 

CLS 

PRINT AT 3,10; “ IzEDTEXtI ”,.. 
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3690 PRINT “THIS IS A TEXT-EDITOR FOR THE 1000 . 
IT HAS THE FOLLOWING FEATURES 


A APPEND 
D DELETE 
J JUSTIFY 
P PRINT 
S SAVE 
X EXECUTE * N 
3700 GOTO 1000 


C CURSOR 
F FIND 

M MEMORY TEST 
R RESET 
T TEST 
Z STOP” 


You can work out for yourself where to put spaces in the string on line 3690. And you 
may like to produce more fancy title graphics than those in line 3680—here’s one 
example which you can easily input as a string of graphics symbols. 



Figure 8.1 


DOCUMENTATION 


No program is complete without an organized set of user-instructions. If you’ve been 
following the way the program was developed, you’ll have a pretty good idea how this 
works; but here’s a summary as a reminder. I’ll assume you’ve keyed the program in and 
SAVEdit. 

First LOAD the program using the instruction LOAD “ZEDTEXT” (or whatever 
name you used). Once loaded, the program will automatically display a title, a short list 
of options, and then await an input command. Any previously SAVEd text will be in 
memory. 

The text is stored as a single string T$ which, for PRINT purposes, is divided into 
640-character segments, called pages. A flashing cursor is displayed to indicate the 
current position in the text. 

Instructions to the program take the form [number] [command letter] [string] where 
the number or string may be omitted in certain cases. Henceforth denote the number by 
n, the command letter by Y, and the string by w. For example a possible command is 
3AFRED, where n = 3, Y = A, w = FRED. 

A sequence of commands may be entered at one time by separating the individual 
commands by the delimiter (shifted Q). Thus the most general command takes the 
form 

niYiw,“”n2Y2W2“”...“”nrYrWr“” 

The final delimiter is optional. To enter a command, type it out and press ENTER. 

A sequence of commands is carried out one by one in order. The available commands 
are as follows. 
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Number Letter 
n Y 

String 

w 

Effect 

n 

A 

w 

Append n copies of w to the text, immediately after 
the cursor. If n = 0 or is omitted, the program 
assumes n = 1. 

n 

C 

— 

Advance the cursor n spaces, (n may be 0, or negative 
for a backward move.) 

— C 

0 

Reset the cursor to the start of the current text page. 
(To change the page, use command P.) 

n 

D 


Delete the next n symbols, including the cursor 
position. If n is negative or omitted, the program 
assumes n = 1. 

n 

F 

w 

Find the nth occurrence of string w in the text, 
starting from the position immediately after the 
cursor; set the cursor to the first symbol of that 
occurrence of w. 

— J 


Left justify the text. (This is effective only on verbal 
text, with at most single spaces between words. It is 
best done at the end of a session.) 

— K 

w 

List the program, starting at line VALw. If w is 
empty, it starts at line 1. 

— L 

w 

Ditto. 

— M 

— 

State current spare memory, omitting workspace. 

n 

P 

— 

Print page n, and set current page to n. 

— R 

— 

Reset all variables to initial state (so that the text 
string T$ becomes empty) and RUN. 

— S 

w 

SAVE the program under the default name 
“ZEDTEXT”, if w is empty, or w if not. This option 
includes a reminder to set up the cassette-player. 

— T 

— 

Set the text to a standard test text. 

n 

X 


Carry out all commands in the currently input 
command sequence n times; then continue to 
subsequent commands. This may be used only once 
in any given input sequence of commands. 

— Z 

— 

STOP the program. 


[In the above table, the symbol — indicates that n or w may be arbitrary or omitted.] 
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SYSTEM VARIABLES 

The main variables used in the program with consistent meanings are the following. 
Numeric 

Cl Cursor position in text T$ 

CN Used to compute screen position of cursor 
CP Ditto 

CPN Current page number 

FC Counter in FIND subroutine 

LN Used to compute screen position of cursor 

N Current command number 

PN Used to compute screen position of cursor 

XC Counter in MULTIPLE EXECUTION subroutine 

String 

K$ Current command letter 

M$ Current sequence of commands from a single INPUT 

T$ Text 

U$ n copies of W$ in APPEND subroutine 

W$ Current command string 

Array 

F (26) Lists line numbers of subroutines for command letters: F (1) for routine A, 
F (3) for C, F (4) for D, and so on by position in alphabet. Entries 2,5,7,8,9, 
14,15,17,21,22,23,25—corresponding to B, E, G, H, I, N, O, Q, U, V, W, 
Y—are available for user-defined and written subroutines. 


POST MORTEM 

If you’ve managed to copy out all of the lines above, and if neither of us has made any 
mistakes, ZEDTEXT will now be in working order. It’s a bit slow, and a bit limited, but 
it illustrates the way such a program is written. 

The speed can be improved by using FAST where possible; but to make any real 
impact you’d need to go to machine code—a daunting task with something this long, 
though easier than most things a professional programmer has to do for a living. 

The limited range of features can be improved. You’ve still got mnemonics B, E, G, 
H, I, N, O, Q, U, V, W, Y to play with: you can add your own subroutines (and initialize 
F (2) or whatever) as you please. Note that you can do this without changing the existing 
program at all: a big advantage of structuring the beast sensibly. 

Even this limited program has features not at first apparent. For example, suppose 
you want to replace every occurrence of JIM by HELEN. You don’t have a replace 
command; but you can use 

FJIM 3D AHELEN 999X 

(where 999 is just chosen to be nice and big). Find JIM, delete it, append HELEN; 
repeat 999 times (or until you hit the end). 

You see why I said ZEDTEXT’s macro-language is a language? That line of 
commands is really a little program in macro-language, which is interpreted by our 
BASIC program ZEDTEXT. You can even see what the “program” does, without ever 
knowing the detailed commands in BASIC. In the same way, the Sinclair ROM interprets 
BASIC commands into Z80 machine code. So—we haven’t just learned about text¬ 
editing; we’ve also learned a little about the way an interpreter works. 
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Let me expand on that remark, because it’s interesting but also potentially misleading. 
When ZEDTEXT executes a string of Macro Commands, it does it this way: 

1. Find the first command. 

2. Decode it. 

3. Look up the corresponding BASIC routine. 

4. Execute that. 

5. Find the next Macro Command to be executed (which, in the case of Xn, means 
either going back to the start of the string or moving on to the next command; and 
otherwise just means move on). 

6. Decode that; repeat until the end. 

Thus, although the 1000 doesn’t speak ZEDTEXT Macro Language as its “native 
tongue”, it’s been given a kind of dictionary to translate into BASIC. But the translation 
is done one command at a time; and on returning to a given command during an Xn loop, 
it retranslates it all over again. It has no way of recognizing “I’ve been here before”. 

The BASIC interpreter in ROM works roughly the same way. Each BASIC statement 
in a program line is “looked up” and turned into Z80 machine code (see later) which the 
lOOO's Central Processing Unit understands. The statement is then executed im¬ 
mediately. The machine then decides which line of program is next to be executed 
(taking account of FOR/NEXT loops, GOTOs, GOSUBs, and IF/THENs—which 
makes things hairier in fine detail) and repeats. Again, it doesn’t know that it’s already 
decoded a given line before, if it meets it again. 

This kind of “translation program” is called an interpreter. Like a United Nations 
interpreter, it reacts mechanically to what is said, sentence-by-sentence; it does not have 
(or require) any overall grasp of the program structure. 

A more sophisticated approach is to use a compiler, which turns the whole BASIC 
program into machine code, but in suitable blocks and not just line by line. A FOR/ 
NEXT loop, for example, would become a corresponding machine code loop; and it 
would be translated only once; not every time it was encountered during a run. A 
compiled program usually runs more efficiently than an interpreted one; but the time 
taken to compile must be offset against any savings. Programs that are going to be used a 
lot can be compiled once, and thereafter run as machine code, which can be SAVEd as 
such. A compiler, of course, is harder to write than an interpreter; and the program must 
be compiled as a whole before it can be run. And even compiled code may not be as 
efficient as tailor-made machine code. Some BASIC compilers for the 1000 are now 
commercially available; and no doubt there will soon be compilers for other languages 
like Pascal or Comal. 
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A simulation of customer-flow in a supermarket, 
which can be adapted to the allocation of hospital beds 
and the queues at filling stations. 


9 Checkout 


This is an example of a computer simulation. A supermarket manager wants to know 
how many checkouts to keep open at a given time of day, subject to information on the 
rate of arrival of customers, distribution of time spent dealing with each customer, and so 
on. The program will attempt to approximate the true sequence of events, keep an eye 
on queue lengths, waiting times, number of checkouts idle, and so forth, and present its 
results. This (ideally) would help the manager decide how many checkouts to keep open, 
and hence how many checkout staff to employ. 

The actual program below is just a first step towards a practical simulation; but by the 
time we’ve written it we’ll be well aware of what extra features it would need, and how to 
extend it. Meanwhile, we’ll keep it relatively simple.- 


DATA STRUCTURE 


What is a good data structure for dealing with N supermarket queues? It’s no accident 
that the word “queue” appears here: the corresponding data structure is designed to do 
exactly what a real queue does, namely accept input at one end and push things out at the 
other. What we want is a list of N queues: that is, a queue array. Recall that to set up a 
queue of length 25 (say) we use DIM O (25), and then special routines to enqueue and 
dequeue entries. For a queue array we do exactly the same thing, but adding an extra 
dimension. If CN is the required number of queues (or checkouts) then we’ll need DIM 
O (CN, 25). The “head” and “tail” pointers H and T, and the lap counter L, also become 
arrays of size CN. 


OPERATION 


We’ll need a main routine to process the queues, say at time-steps of 1 minute (simulated 
time, not real time, that is!). At each time step this will have to: 

1. Decide how many new customers join the queues. 

2. Decide how long each of them will take to pass through the checkout (i.e. how 
many goods they’ve bought). 

3. Enqueue them according to some reasonable “customer strategy”. 

4. Decrease by 1 minute the waiting time of the customer at the head of each queue. 

5. Dequeue customers whose time has decreased to 0. 

In addition, we’ll arrange for: 

6. The production of a graphic display of the current situation. 
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After a chosen number of time-steps (say 100) the program should stop, and display an 
analysis of the way the queues behaved. Some useful quantities would be: 

• The average length of a queue. 

• The maximum length of a queue. 

• The average time a customer spends waiting in a queue. 

• The maximum time a customer spends waiting in a queue. 

• The average number of checkouts idle. 

These quantities will be evaluated by various “system variables”, and the main program 
must keep these up to date; so we’ll also need: 

7. Update the system variables. 

8. Display analysis at end of simulation run. 


ENQUEUE AND DEQUEUE 

Let’s build these subroutines first, because we’ve already got them worked out (see 
page 22). Assume we are working on queue number I and wish either to enqueue an 
extra number V, or dequeue a number and call it V. 

Initialize: 


10 DIM Q (9,25) 

20 DIMM(9) 

30 DIMT(9) 

40 DIML(9) 

We are envisaging a maximum of nine queues here. (To save memory we could first 
input the number CN of checkouts, then change ail 9s above to CN; but there’s plenty of 
room in 16K so why bother?) 


1000 

1010 

1020 

1030 

1040 

1050 

1060 

1070 

1080 


REM lENQUEUE 


IF H (I) = T (I) AND L (I) = 1 THEN GOTO 1070 
LETQ(I,T(I)) = V 
LETT(I) = T(I)-I-1 
IF T (I) > 25 THEN LET L (I) = L (I) + 1 
IF T (I) > 25 THEN LET T (I) = 1 
RETURN 
PRINT AT 21,0;‘ 


QUEUE FULL 


STOP 


(If a queue of length 25 gets full, the run stops; but this indicates that queues have grown 
much too large for comfort, and more checkouts are needed.) 


1100 

1110 

1120 

1130 

1140 

1150 

1160 


REM [DEQUEUE 


IF H (I) = T (I) AND L (I) = 0 THEN RETURN 
LETV = Q(I,H(I)) 

LETH(I) = H(I) + 1 
IF H (I) > 25 THEN LET L (I) = L (I) - 1 
IF H (I) > 25 THEN LET H (I) = 1 
RETURN 




As it happens, when we dequeue, V is always 0; but we don’t know this at this stage in the 
writing; anyway, it would be nice to check. We’re not worried if a queue gets empty 
(unlike ENQUEUE where a full queue spells disaster) so line 1110 doesn’t ask for a 
“QUEUE EMPTY” display as line 1070 did. 

The initialization of T and H isn’t quite what we want, though: the ENQUEUE and 
DEQUEUE routines assume H and T start at 1, not 0. So we need to add: 

50 F0RI=1T09 
60 LETH(I)=1 
70 LETT(I) = 1 
80 NEXTI 

GRAPHICS 

The next routine sets up CN “checkouts” with spare lines for the queues to be printed 
out (by another subroutine which follows). 


12W 

REM ICHECKOUT GRAPHICS 1 



1210 

CLS 



1220 

FORI= ITOCN 



1230 

PRINTAT2*I- 1.3;“HHH CHR$(156 + I) 

1240 

NEXTI 



1250 

RETURN 



To print the queues: 



1300 

REM (queue PRINT 1 



1310 

LETX = H(I) 



1320 

LETQ$ = “” 



1330 

IF Q (I. X) = 0THEN GOTO 1350 



1340 

LET Q$ = Q$ + CHR$ (156 + Q (I, X)) 


build inverse video 

1350 

IF X = T (I) THEN GOTO 1390 



1360 

LETX = X+ 1 


copy of queue 

1370 

IFX>25THEN LETX = 1 



1380 

GOTO 1330 



1390 

PRINTAT2*I,7;Q$;“n” 

[— print it 

1400 

RETURN 




Each queue is printed out in inverse video: the numbers in the queue represent the 
waiting time for that individual (i.e. the time needed for him/her to pass through the 
checkout). 


CUSTOMER HANDLING 

Next, the subroutines dealing with customers. First we need to decide how many new 
customers join the queues during one time-step (one “minute”). For simplicity I’ll use a 
random number of arrivals, generated in the obvious way, to produce an average arrival 
rate AR. I’ll input AR itself later. 




1500 REM IaRRIVALS | 

1510 LET NA = INT (2 * AR * RND) 

1520 RETURN 

Well, that’s almost too trivial to have as a subroutine at all; but I’m going to leave it like 
that in case someone wants a more complicated distribution of arrivals at some later 
stage in the development of the program. It will be easier to change it if it’s a subroutine 
on its own. NA, of course, is the number of customers arriving. 

What do the customers do when they join a queue? They sit and wait. The question is, 
for how long? Each customer will have bought a certain number of goods, which will take 
a certain time to process. For ease of display and computation. I’m going to assume that 
each customer is assigned a waiting (i.e. processing) time that is a whole number of 
minutes, and at least 1. 

For illustrative purposes, suppose we want to produce a distribution of waiting times, 
so that of every 30 customers, on average: 

4 customers take 1 minute to process 
" " 2minutes" " 

" " 3 " 

M // ^ ,, ,, n 

ft tt ^ n ff ff 

Looks like a messy thing to program, but it’s not. Take an easier case: suppose that out 
of every 6 customers, on average, we want 

1 customer to take 1 minute 
1 " " 2 minutes 


1 " " 6 minutes 

Obviously we “roll a die’’ to decide the length of time for each customer. That is, we’d 
use INT (1 -I- 6 * RND)—see Timex/Sinclair 1000, p. 34. For the more complicated 
distribution above, we need to concoct a 30-sided die, such that 4 sides are labelled “1”, 
6 sides “2’’, 10 sides “3’’; 8 sides “4’’, and 2 sides “5”. 

Here is such a die: 

LET D$ = “111122222233333333334444444455’’ 

If we can pick a digit out of D$ at random, we can “roll’’ the die too; and that’s not hard 
to arrange: 

LET NT = VAL D$ (INT (1 + 30 * RND)) 

OK, here’s the scenario. When a new customer arrives, (s)he is going to select which 
checkout to go to by some strategy. The waiting time is assigned using the “die’’ D$. For 
the moment I’m only going to illustrate the simplest strategy, “choose a queue at 
random”; but you might like to think about modifying the program to allow two others: 

1. Choose the shortest queue (or at random from the shortest ones if there is more 
than one)—I’ll add this in later. 

2. Choose the queue with shortest total waiting time (which a customer could 
estimate fairly well by looking at how much stuff is in people’s baskets, so it’s 
reasonably realistic). 

That gives us two new subroutines: 

16W REM [strategy' 


6 

10 

8 

2 


1610 LET I = 1 + INT (CN * RND) 
1620 RETURN 





(which decides which checkout a given customer will go to, and calls it I); 


1700 REM [NEXT WAITING TIME 
1710 LETNT = VALD$(INT(1+30*RND)) 
1720 RETURN 
We’ve also got to initialize D$: 


MAIN PROGRAM 

Now comes the bit that organizes all the rest: it works out what happens during the Nth 
time-step. First we initialize a variable to count the steps, 

100 LET STAGE = 0 

Next we arrange for the operator to input a couple of variables that need to be decided 
before the subroutines can work: 


300 PRINT “SUPERMARKET CHECKOUT SIMULATION”,,, 
310 PRINT “INPUT NUMBER OF CHECKOUTS < = 9” 

320 INPUT CN 

330 PRINT “INPUT CUSTOMER ARRIVAL RATE” 

340 PRINT “(AVERAGE PER MINUTE)” 

350 INPUT AR 
400 GOSUB1200 
Now we’re all set for the action: 


500 

510 

520 

530 

535 

540 

545 

550 

560 

570 

580 

590 

600 

610 

620 

630 

640 


REM IONETIMESTEPI 

LET STAGE = STAGE -I- 1 

PRINT AT 21,20; “STAGE = □ STAGE 

GOSUB 1500 

IF N A = 0 THEN GOTO 590 

FORX= ITONA 

GOSUB 1600 

GOSUB 1700 

LETV = NT 

GOSUB 1000 

NEXTX 

FORI= ITOCN 

IF H (I) = T (I) AND L (I) = 0 THEN GOTO 640 
IF O (I, H (I)) = 0 THEN GOSUB 1100 
IF O (I, H (I)) = 0 THEN GOTO 640 
LETQ(LH(I)) = Q(LH(I))- 1 
NEXT I 


[— number arriving? 

|— choose queue 
I— find waiting time 

[—enqueue 


decrement front 
— ofqueue, and 
dequeue if zero 




sprint queues 


650 FORI = lTOCN 
660 GOSUB1300 
670 NEXT I 
680 GOTO 500 


Not bad. But it won’t ever stop! If we want to run a specified number of stages, then we’ll 
need to tell the machine how many, and when to come out of the loop from 680 back to 
500. So we’ll add: 


360 

370 

675 


PRINT ‘‘INPUT NUMBER OF STAGES IN RUN ’ 
INPUT NSTAGE 

IF STAGE = NSTAGE THEN GOTO 2000 


check if 
hrun has 
ended 


At line 2000we’ll put a routine that produces an analysis of the main features of the run. 

That raises all sorts of interesting questions, because we’ll have to keep track of those 
features as the run proceeds, and so far we haven’t built anything into the program that 
will do this. So let’s take a look at the problems involved. 


SYSTEM VARIABLES 

To keep track of what’s happening, we need to set up various new variables, update them 
as necessary, and use them to calculate the information required in the final analysis of 
the run. 

First, let’s decide what we’d like to know. A few suggestions: 

ML = maximum length of a queue. 

AL = average length of a queue. 

MW = maximum time a customer waits in a queue. 

AW = average time a customer waits in a queue. 

AE = average number of empty queues (i.e. idle checkouts). 

Of these, ML and MW are the easiest to deal with. All we have to do is scan the queue 
lengths (wait times) at each stage (as each customer joins) and increase ML or MW if this 
number is larger than the current value. So first we have to initialize: 

110 LET ML = 0 
120 LET MW = 0 

Then we need two arrays W and N which hold the total waiting time and length of a given 
queue: 

130 DIMW(9) 

140 DIMN(9) 

(As before, if we INPUT CN earlier, we can DIM W (CN), etc. to save space; but it’s not 
necessary.) 

Now for those averages. You have to think quite carefully what they mean. The way to 
get an average is to total a lot of numbers and divide out by how many of them there 
are—but you have to total the right things! The sensible way is to keep a running total, 
and a running count, and divide one by the other. 

Thus to get the average length of the queue, we need a running total length TL, which 
is updated for each queue once per stage. The running total of queues involved, at CN 
per stage, is just CN * STAGE. So AL = TL/(CN * STAGE). But where do we update 
TL? 

First we initialize it: 

150 LETTL = 0 




Then we decide where to find the queue lengths: the easiest place is during the QUEUE 
PRINT routine: 

1395 LETN(I) = LENQ$ 

We haven’t finished with TL yet, but let’s put the rest of the calculation into an 
UPDATE subroutine, to be written below; and start working on AW, the average 
waiting time. Averaged over what? Average per customer. A given customer’s waiting 
time is the total waiting time of the queue he joins, at the moment he joins it, plus his own 
waiting time. So most of the updating will get done during ENQUEUE, where the 
customer joins the queue. Further, we need to keep a check on the total number of 
customers that has passed into the system, with a variable TOTCUS. And TW will total 
the waiting times. Sounds messy? Just keep a clear head! 


160 

LETTW = (> 

170 

LET TOTCUS = 0 

Updating 

is done here: 

642 

FORI = ITOCN 

644 

LET W (I) = W (I) - 1 + (W (I) = 0) 

646 

NEXT I 

1002 

LET TOTCUS = TOTCUS + 1 

1004 

LETW(I) = W(I) +V 

1006 

LETTW = TW +W(I)- 1 


UPDATING 

The update routine also takes care of the “average number of checkouts empty” 
variable, by making a running total TE and dividing by the value of STAGE. Initialize: 


180 

LETTE = 0 



1800 

REM lUPDATE 1 



1810 

LET EC = 0 

1— set empty counter EC 

1820 

FORI = ITOCN 



1830 

IF N (I) > ML THEN LET ML = N (I) 

|— update ML 

1840 

IF W (I) > MW THEN LET MW = W (I) 

1—update MW 

1850 

IFN (I) = 0THEN LETEC = EC + 1 

1— update EC 

1860 

LETTL = TL + N(I) 

update TL 

1870 

NEXT I 



1880 

LETTE = TE + EC 

~~V- update TE 

1890 

LET AL = TL/(CN * STAGE) 



1900 

IF TOTCUS = 0 THEN GOTO 1920 



1910 

LET AW = TW/TOTCUS 


— compute averages 

1920 

LETAE = TE/STAGE 



1930 

RETURN 






Before we get too carried away with the amazing success of this subroutine, we’d better 
take care of one minor point: there’s no way to get into it yet. We need to modify the 
main program: 

672 GOSUB1800 


ANALYSIS 


Coming down the home straight now. All we need is to work out a few more system 
variables, and print it all out. 


2000 REM I ANALYSIS | 

2010 CLS 

2020 PRINT “□□□□□□□□□ ANALYSIS”,,, 

2030 PRINT “NUMBER OF CHECKOUTS = □ ”; CN 
2040 PRINT “CUSTOMER ARRIVAL RATE = AR 
2050 PRINT “CUSTOMER STRATEGY: RANDOM” 
2060 PRINT “NUMBER OF STAGES = □ ”; NSTAGE 
2070 PRINT 

2080 PRINT “MAXIMUM LENGTH = ML 
2090 PRINT “AV'ERAGE LENGTH = AL 
2100 PRINT “MAXIMUM WAIT □□□ = MW 
2110 IF TOTCUS = 0 THEN GOTO 2150 
2120 PRINT “AVERAGE WAIT □□□ = □”; AW 
2130 PRINT “AVERAGE EMPTY □□ = □”; AE 
2140 STOP 

2150 PRINT “AVERAGE WAIT □□□ = 0” 

2160 GOTO 2130 

A SAMPLE RUN 


Once you’ve got the above listings typed in (and no doubt re-debugged them, typing 
errors being almost unavoidable in this game) the simulation is ready. Type RUN. When 
asked, INPUT the number of checkouts (say 7), the arrival rate (say 4) and the length of 
run (say 10, since the program runs fairly slowly). You’ll get a graphic display like this, 
changing at each stage according to the way the customers behave. Then, after the 10th 
stage, comes the Analysis. 

Here’s a typical series of runs, with the arrival rate AR = 3 throughout, and NSTAGE 
= 20; all the values CN = 1,2,3,..., 9 have been tried in turn. (You can of course get the 
computer to do all this for you, by suitable modifications—but for an exploratory 
attempt it’s not really worth the bother.) The analysis is summarized in a table: 
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CN 

ML 

AL 

MW 

AW 

AE 

1 

QUEUE FULL AT STAGE 15- 

RUN STOPPED 


2 

23 

12.675 

62 

31.711864 

0.2 

3 

15 

5.8333333 

46 

18.44 

0.2 

4 

10 

3.9125 

27 

12.5 

0.25 

5 

11 

3.31 

31 

11.565217 

0.9 

6 

7 

1.7 

18 

7.4418605 

2 

7 

6 

1.81642857 

15 

6.7884615 

1.75 

8 

5 

1.03125 

16 

5.4324324 

3.85 

9 

4 

1.0722222 

13 

4.4444444 

3.1 


So, for example, with 7 checkouts the longest queue in the 20 stages run was 6; the 
average was about 1.8, the longest wait was 15 minutes, the average wait about 6.8 
minutes, and on average 1.75 checkouts were idle. The extra decimal places provide a 
totally spurious suggestion of accuracy, and shouldn’t be believed. 

These are probably barely acceptable figures: you wouldn’t want customers to wait 
much longer than that! The figures with 6 checkouts are a trifle worse; with 8, better on 
average; with 9 better still. With 5, they’re terrible! So you conclude that you need about 
7 checkouts. 

Of course, 20 is a rather short run; but armed with this rough estimate, you can try 
longer runs with 7 or 8 checkouts. I took NSTAGE = 100, AR = 3, and got: 


CN 

ML 

AL 

MW 

AW 

AE 

7 

11 

3.5857143 

34 

11.701%! 

0.95 

8 

12 

1.875 

38 

7.%20253 

2.85 


Now 7 looks less good; and 8 is acceptable. Conclusion: we need 8 checkouts. 
(Incidentally, a run of 100 stages takes about 6 minutes in FAST, which disables the 
graphics; by cutting out display routines you could reduce this a little.) 


ALTERNATIVE STRATEGIES 

You won’t always get exactly these figures, of course, because of the random element in 
the simulation; but they’re fairly typical. However, you may well suspect that the figures 
are unreasonably distorted by the choice of customer strategy: in practice, shoppers do 
not choose the checkout to join at random! 

We can easily modify the existing program to permit different strategies: simply 
change the subroutine at 1600, or better still, allow a range of strategy subroutines and 
call the required one when starting the run. Note that it is this easy precisely because we 
have broken the program up into subroutines. 

For example, suppose the customer sizes up the queues, sees which are shortest, and 
joins one of the shortest ones (at random if there are two or more). Then we would need 
a new strategy subroutine; and for ease of modification we’ll put it at line 3000. Here’s 
the guts of it: 
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3000 

3010 

3020 

3030 

3040 

3050 

3060 

3070 

3080 

3090 


LETZ= 1 
LETMQL = 25 
FORI= ITOCN 

IF N (I) < MQL THEN LET MQL = N 
NEXT I 

FORI = ITOCN 

IF N (I) <> MOL THEN GOTO 3090 
LETB(Z) = I 
LETZ = Z+ 1 
NEXT I 


(I) 


find length 
— of shortest 
queues 


list shortest 
queues 


3100 LETR= 1+ INT((Z-1)*RND) 
3110 LETI = B(R) 

3120 LETN(I) = N(I) +1 
3130 RETURN 


select one 
at random 


As always, there’s some initialization to take care of, and a bit of tinkering with the 
original program. First, DIM B... 

190 DIMB(9) 

Next, we want to call either our old strategy at 1600 or our new one at 3000. That’s easy 
enough: 


380 PRINT “CHOOSE STRATEGY: 1. RANDOM. 

2. SHORTEST QUEUE. ” 

390 INPUT STRAT 

Then we change the branch to STRATEGY: 

545 GOSUB A (STRAT) 

We here envisage an array A that holds the strategy subroutine line numbers: if we add 
even more strategies to the repertoire, we can just modify A. But it needs initializing: 

200 DIM A (2) 

210 LETA(1) = 1600 
220 LETA(2) = 3000 

Finally, we need to tidy the ANALYSIS: 

2050 PRINT “CUSTOMER STRATEGY: □ (“RANDOM” AND STRAT = 1) + 
(“SHORTEST □□□□□□□□□ QUEUE” AND STRAT = 2) 

With more than two strategies, this might get clumsy —you can work out a better way! 

Incidentally, if you object to all those LETs in the initialization, you can RUN, wipe 
them out, SAVE, and then GOTO 10. I don’t really like doing this, because I have a 
nasty habit of typing RUN at the wrong moment. A fairly safe way is to add 

9000 SAVE “CHECKOUT’ 

9010 GOTO 10 

and SAVE using GOTO 9000. Then the GOTO 10 is automatic on loading. You could 



also fit some pretty title graphics in here. It’s questionable whether getting rid of all the 
LETS is really worth it: memory is not at a premium in this program. But automatically 
running SAVEs is always a nice touch. 

Anyway, we now have an additional option in the simulation: the choice of strategy. 
Let’s see what effect it has on the results. RUN as before; but when asked for the strategy 
input 2. Here’s a sample with the same inputs as before: see how the results change! 


STRAT=2, AR = 3. 


CN 

ML 

AL 

MW 

AW 

AE 

1 

2 

QUEUE FULL AT STAGE 14—RUN STOPPED 

10 5.55 35 14.657895 

0.05 

3 

4 

2.25 

11 

10.886364 

0.05 

4 

5 

2.6 

16 

9.9795918 

0.65 

5 

3 

1.57 

10 

7.3695652 

0.5 

6 

3 

1.4583333 

11 

5 

1.15 

7 

2 

0.69285714 

7 

5.7272727 

2.95 

8 

1 

0.4375 

4 

3.6666667 

4.5 

9 

2 

0.61666667 

6 

2.1698113 

4 


This time we get acceptable figures with only 4 or 5 queues. Note the dramatic jump in 
empty checkouts (AE) between CN = 5 and CN = 6. Again, the shortness of the run (20 
stages, as before) may be causing distortions, so you should now try CN in the range 
4-5-6-7 with, say, 100 stages. (I suggest FAST again!) Experiment, and imagine you’re 
the Manager deciding how many staff to hire. Or possibly the Consumer Watchdog, 
deciding whether the times are acceptable to customers ... 



CHECKOUT display: customers in queues at nine checkouts, with variable waiting times. The queue 
lengths are almost equal, because customers here have chosen to join the shortest queue. 
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DOCUMENTATION 


The program is pretty much self-explanatory; but here’s a summary of its main points. 

LOAD “CHECKOUT” and RUN (unless you’ve done the self-running version). 
INPUT, when asked, the number of checkouts, average rate of arrival of customers, 
desired length of run, and chosen customer strategy (1 = random choice of queue; 2 = 
choose only among the shortest queues). Use FAST to disable graphics and speed 
calculations, if desired. 

The program will perform the simulation, and provide an analysis of the results, listing 
the above variables, and also: 

The maximum queue length. 

The average queue length. 

The maximum waiting time per customer. 

The average waiting time per customer. 

The average number of checkouts empty. 

System variables 


Numeric 

AE 

Average number of checkouts empty 


AL 

Average length of queues 


AR 

Customer arrival rate (number per minute) 


AW 

Average waiting time 


CN 

Number of checkouts 


EC 

Counter in UPDATE routine 


ML 

Maximum length of queue 


MQL 

Minimum length of queue 


MW 

Maximum waiting time 


NA 

Number of customers arriving 


NSTAGE 

Number of stages in simulation run 


NT 

Next waiting time 


STAGE 

Current stage in run 


STRAT 

Customer strategy number 


TE 

Running total of empty checkouts 


TL 

Running total of queue lengths 


TOTCUS 

Running total of customers arrived 


TW 

Running total of waiting times 


V 

ENQUEUE or DEQUEUE variable 

Strings 

D$ 

Dice—distribution of waiting times 


Q$ 

Used in QUEUE PRINT routine 

Arrays 

A (2) 

Strategy line numbers 


B(9) 

List of queues of minimum length 


H(9) 

Head pointers for queue routines 


L(9) 

Lap counters for queue routines 


N(9) 

Length of queues 


Q(9,25) 

Queues 


T(9) 

Tail pointers for queue routines 


W(9) 

Total waiting times 


Subroutine line numbers 

10 Initializations 

300 Request for variables CN, AR, NSTAGE, STRAT 

500 One time step—main program 

1000 Enqueue 

1100 Dequeue 

1200 Checkout graphics 



1300 

Queue print 

1500 

Arrivals 

1600 

“Random” strategy 

1700 

Next waiting time 

1800 

Update 

2000 

Analysis 

3000 

“Shortest queue” sti 

9000 

Autosave 


Projects 

If you’ve followed the instructions this far, you ought to be able to tinker with the 
program without much trouble; or even insert new subroutines allowing extra options 
(but be careful—you don’t want to spend twenty minutes setting things up for each 
run!). Here are some suggestions—and some additional simulations you can try. 

1. Change the waiting times. The “30-sided die” D$ controls the distribution of waiting 
times. Change it, and see what difference it makes. Better still, let the computer build up 
D$ given the required distribution. 

2. Remove transients. I’ve ignored almost completely the problem that we start with an 
“empty supermarket”—no customers—so the first few stages are not entirely repre¬ 
sentative. It might be more sensible to run the program for, say, 10 stages; reset all 
variables (except queues and related ones); then start the run proper. Try to write a 
program that allows this. 

3. Multiple runs. You don’t want to sit there all day keying in values 1,2,3,... for CN. 
Get the computer to do it; you’ll need to store the various analyses in arrays now, and 
modify the final display. Oh, yes—and change the QUEUE I^LL jump so that the 
machine does something useful, rather than just stopping. 

4. Coincident birthdays. N people at a party compare dates of birth. Ignoring the year, 
what are the chances that at least two of them have the same birthday? 

Simulate it. You’ll need a 365-sided die (don’t use a D$; use 365 * RND). Don’t worry 
about leap-years unless you’re a perfectionist. Generate N birthdays, compare, count 
coincidences; repeat 50 times (say); print the results. 

Try N = 5,10,15,20,25,30,... What size must N be for the chances to be more than 
even (probability V2) that a coincidence occurs? Unless you know the answer, you’ll be 
surprised... 

5. Gas station. This has a line of PN pumps, each capable of accommodating two cars 
at a time, but serving only one. Arriving cars join one of two queues (for each side of the 
pumps), which they cannot leave until served. The queues move whenever a space on 
that side becomes empty. Given randomly distributed arrival and serve times, find 
maximum and average queue lengths, waiting times, number of pumps idle, etc. 

Generalize to PL lines, each with PN pumps. 

6. Hospital beds. A hospital ward has BN beds. Patients arrive at random, and stay a 
random number of days. Beds are allocated as they become spare. If there are none, the 
patient goes on the waiting list. What is the optimum number of beds to ensure that the 
waiting list doesn’t get too long, and that as few beds as possible remain empty on 
average? 

If you think this is a thinly disguised rewrite of CHECKOUT—you’re right! But the 
sensible numbers are different, and you’ll need new graphics. 


81 



A case history in educational computing: test your French 
vocabulary and fly to the Moon at the same time! 


10 French Countdown 

by Eric Deeson 


Eric runs EZUG, the Educational ZX User's Group. Here he writes of his experiences at the sharp 
end of program design and distribution, where theory must sometimes be tempered with practical 
considerations. Up till now, provided there’s memory to spare, I haven’t worried too much about 
saving space. But long programs take a long time to load from tape; and in educational computing 
particularly, long waits lead to boredom and the whole process can be subverted before the 
program ever starts running. So here, straight from the horse’s mouth (no offence, Eric!) are some 
valuable tips on program design and a blow-by-blow account of their use; some special tricks to get 
more from your 1000 \ and some advice about selling and distributing software on the open 
market. ^ 

INTRODUCTION 

Everyone knows that doctors at cocktail parties have a big problem. As soon as they 
mention their job, they are faced with a list of symptoms to diagnose. Teachers tend not 
to be invited to cocktail-parties; however, they have been known to drop in on the 
occasional social gathering. As a computing teacher I have the doctors’ problem—if 
another teacher finds out what I do, the reaction is likely to be “Oh, could you write a 
program to help nriy 3C with their quantum mechanics?” Or the details of the Spartan 
wars. Or the two-times table, or whatever. My weak smile is sometimes followed by total 
inaction; sometimes an idea grows and reaches the stage of several scraps of paper. Very 
occasionally, after many hours’ work, a polished program results. FRENCH COUNT¬ 
DOWN came about in that kind of way. The story of how it reached a polished version 
can now be told. I would like to use it to illustrate how one can produce complex software 
by way of a methodical approach. This « a learning program, one that can be (and is!) 
used by children at home or at school. But the principles of structured program 
development are generally applicable. There are also various coding tricks described, at 
least some of which you may find novel and useful. 

Any program, I think, has to meet the following criteria. 

• It must do the job for which it was designed. 

• It must do so efficiently and with minimum effort on the part of the user. 

• Once the program is loaded, it should expect no computing knowledge at all. And 
the user should never be in doubt what to do. 

• The screen display must be pleasing—effectively laid out, uncluttered, easy to 
follow. 

• The user must enjoy working with the program. 

The designer needs, therefore, to know not only about programming, but about com¬ 
munication. And he/she must know the subject concerned. In the case of a teaching 
program, that theoretically means that three people form the development team—a 
competent programmer, a specialist in the teaching of the subject at the level concerned, 
and someone with an eye for language and layout. Brilliant as I am, I can’t do all that for 
a French teaching program, and I consulted several teachers about different aspects of 
the software. 




PROGRAM DESIGN 


Teachers have to think on their feet a lot, fielding sudden questions with (one hopes) 
effective as well as immediate answers. I suspect, therefore, that computing teachers are 
more able than most programmers to write a workable program without much planning. 
However, that applies only to short chunks of code with straightforward objectives. The 
temptation to rush at a long complex program without thinking must be resisted. I’ve not 
been able to resist the temptation sometimes—and I’ve always got in a heck of a mess in 
the coding and not been satisfied with the end result. We need a structured approach to 
the design and coding of programs likely to occupy more than a couple of dozen lines or 
so. A common type of structured development is called top-down programming. We can 
illustrate it like this: 



Figure 10.1 


Note the word “tested” there. A major advantage of top-down programming is that 
one can test each individual procedure before linking it with the rest. 

In essence, then, we must develop the initial idea into a number of fairly water-tight 
sections. Each section is called a module —it is developed, tested and polished on its own 
as a subroutine. The final program is a suite of such modules, suitably linked together 
and suitably tested and polished as a whole. Testing may seem irksome, for it is more 
than just trying the procedure yourself a couple of times to see if it works. The 
programmer must do his best to make sure it succeeds in all conceivable circumstances. 
If it doesn’t, what use is it? 

The final program is therefore a set of modules, or subroutines, linked together in 
some suitable way. We can view it like this: 


> 


START 

MODULE A 


1 ^ 


B 

BB 

N-1 


endI 

Fiourtf If) 7 




Actually I’ve been using words rather carelessly. It may not really matter here, but 
there are differences between subroutines, modules and procedures. 

A module is a self-contained section of a program, one with a logical identity and 
which can be tested in isolation. 

A subroutine is a section of code designed to carry out a specific task. There are two 
kinds. The kind we are used to, called by GOSUB and terminated by RETURN, is a 
closed subroutine. An open subroutine, on the other hand, is a set of instructions in a 
larger one—it still has a specific task but does not use GOSUB/RETURN. 











A procedure is a sophisticated closed subroutine with its own set of variables. The 
1000 does not offer procedures in this sense. 

From now on. I’ll use the word “module” to indicate a conceptual part of the final 
program. As far as coding is concerned, a given module may be a set of open and/or 
closed subroutines. 

As I do quite a lot of coding, I find it useful to reserve different parts of the computer 
memory for different types of module. The 1000 memory map for my programs is laid 
out like this: 


r® 

p50 

pi(» 

p500 

pl000 

pl5(W 

p2000 

p5(W0 

p9998 

REMS 

«TART 

INTRO 

COMMON 

ROUTINES 

MAIN 

PROGRAM 

SPECIAL 

ROUTINES 

DATA 

ROUTINES 

GRAPHICS 

ROUTINES 

SAVE 


Figure 10.3 

You’ll see the differences between the sections when we get to look at the develop¬ 
ment of FRENCH COUNTDOWN. 

Here are the stages of the structured modular development of a program. The stages 
marked * involve particularly careful testing, by the writer, by others, by victims 
representing the final target population. 

1. Definition of program aims and objectives. 

2. Development of plan of approach leading to outline flowchart and story-board. 
(I’ll explain these posh terms later.) 

3. Analysis of the overall program into logical modules, based (theoretically) on 
the boxes in the outline flowchart. 

4. Developing the main program module (*). 

5. Developing, coding, and testing each module and subroutine. 

6. Linking the modules together (*). 

7. Revising as necessary (*). 

8. Polishing the main and subsidiary modules for speed, layout, efficiency (*). 

9. Adding the opening and closing routines (*). 

10. Polishing and testing the whole thing. 

11. Preparing documentation as necessary from the records developed earlier. 

Records? Yes—keep the paperwork associated with steps 1-3 above, and during the 
coding stages maintain vigorously the following lists: 

{a) Variables and their significance. 

{b) Addresses of modules and subroutines. 

(c) Graphics plotting data. 

At the end, all this may be condensed into one page or so for filing—perfectly adequate 
if you keep your REMs in the listing. 

Remember that no program is ever perfect—if it is worth keeping it is worth im¬ 
proving every so often. At the very least, you will come to find parts of it impossibly 
clumsy in the light of your growing expertise—those summary records in the file will 
make modification fairly straightforward. 


DESIGNING FRENCH COUNTDOWN 

By now you will have forgotten that I’m supposed to be talking about the development of 
a specific program—FRENCH COUNTDOWN, a language teaching unit. 

How was all the theory of the last section applied in this case? Let’s take it step by step. 

Step 1: Definition of aims and objectives 

The original cocktail-party request was for a program with which individual pupils could 
test their elementary French vocabulary. That overall plan led to the following aims. 





1. To draw at random from a pool of vocabulary items, requesting translation either 
from English to French or the other way. 

2. To keep count of score. 

3. To do all this within the context of a simple game. 

4. To provide a printout of the correct versions of questions answered wrongly. 

5. To set up the pool so that it could be easy for the teacher/parent to change the 
vocabulary tested. 

There was only one specific objective—that when the user had run the program two or 
three times he/she would know the vocabulary better. (That objective indicates that, in 
educational jargon, this is a drill program rather than one for just testing knowledge. I 
admit that the original request was for a simple test; trust me to think I know better.) 

Step 2: Development of plan of approach 

The above aims can be expressed in a very simple flowchart. 



Figure 10.4 
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The skeleton of a set of modules is appearing out of the gloom already. Some are tiny 
routines, like the C-loop (setting a given number of questions); others, like getting an 
individual question on screen, and checking out the answer, are going to be complex and 
will need much more definition. 

What about that ADVANCE box? Therein lies the game aspect of this program. 
Some kind of “thermometer” display is needed, a graphics routine to show how suc¬ 
cessful the user is. Many programs of this nature, if they have a graphics game angle at 
all, stick to getting a train to move further and further along a track. Not me. With an eye 
on^ Space Invaders I settled on launching a rocket ship. Each correct answer would 
build the ship up further on the launch-pad, like sketch (a) below. Full marks at the end 
of the run, and the ship would buzz off around a screen full of stars. Sketch (b) shows that 
dream. (I didn’t succeed in that, I tell you now.) 



i?es^o*tCe 

a 




Figure 10.5 


Sketches like this form what is called a story-board (a term intended to show my keen 
knowledge of the film industry, another industry in which I have failed to make a 
fortune.) 

Boxes 3,4, and 5 are going to make the main program modules. 3 is simple—it needs 
no more extension as it will form a nice little FOR... NEXT loop. Box 4, though, needs 
more thought. Here the program must select a question from the pool, check that it 
hasn’t already been used, and present it on screen. To some extent the routines there will 
depend on the data structure used to hold the pool of questions, but at this stage we can 
break box 4 down into smaller modules like this. 



Figure 10.6 







Maybe in practice 4a will need further subdivision, in particular to allow random choice 
of translation direction. Anyway, leave it for now. Same with 5,6 and 7—they’re likely 
to become complex in practice. 

(Actually, at this stage of development, my plans for boxes 6 and 7 were—to say the 
least—vague.) 

CODING 

The foregoing took several hours, all without setting a single program line down on 
paper or in memory. Not only that, but those several hours were spread over several 
days. That is an accidental part of my program development procedures, for I do have 
other things to do than sit at a keyboard. But it is now an explicit part of my system. Even 
when I have a brilliantly exciting program idea I refuse to do any coding until a little while 
has elapsed in which my subconscious can kick routines around. 

But now it’s time to code! We’re on to steps 4,5 and 6 at last. First the barest skeleton, 
based on my standard memory map (sketched earlier): 


Code Direct data Variables list 


1 

REM |rEMS| 


49 

REM 1 START 1 


50 

SLOW •LET 08=1000 


495 

GOTO PROG • LET PROG = D8 

PROG: Start main 



program (1000) 

498 

REM 1 SERVICE ROUTINESi 


999 

REM IPROGI 


1005 

FORC = A1TOB0 •LETA1 = SGNPI 

C: Main loop counter 

1090 

NEXT C • LET B0 = CODE “ H ’ 


1099 

REM [FINISH OFFi 


1490 

FAST 


1495 

STOP 


1498 

REM [SPECIALROUTINESi 


1999 

REM OUESTIONSl 


4999 

REM 1 GRAPHICS 1 


9997 

REM 1 VERSION D ATE 1 


9998 

SAVE TRENCH COUNTDOWN" 


9999 

GOTO START • LET D1 = CODE ‘‘M " 

START: Real 


• LET START = D1 

start (50) 


It's a start! And immediately some points arise: 

1. These fragments of code are accompanied with (column two) directly entered 
data, and (column 3) the growing list of variables. 

2. Sprinkle REMs all over the place however good the paper-work. But give them 
line numbers just below the corresponding start-points—then when REMs are 
erased the line number flow won’t be broken. 

3. Also, it's a good idea to put remarks in inverse—boxed in these listings. That 
makes them show up very clearly on screen or printout. 




4. GOTO and GOSUB addresses need not be numbers in Sinclair BASIC— give 
them meaningful names; four or five characters is enough. 

5. To save memory, I code all commonly used numbers—thus D1 (line 9999) is my 
standard code for 50. 

6. The main parts of my programs run in SLOW (line 50), but I code and edit in 
FAST. So there’s a FAST at the end right from the beginning (line 1490). 

7. Interruptions “occasionally” occur when I’m working, and at the back of my mind 
is always the dreaded “white out” (which happens very rarely nowadays). So the 
SAVE routine goes in at once—lines 9998/9. Just before that I keep an updated 
version REM, so that I don’t accidentally restart work on an outdated part- 
program. 

Memory-saving is important. I occasionally do write 1000 programs that approach the 
16K barrier, but even those that don’t are best kept compact to minimize saving/loading 
time. The main memory-saving trick is to code all common numbers as two-character 
symbols. We’ve met three already—here’s the complete list. It covers the numbers 0 to 
30, so important for loops and PRINT ATs; it also covers numbers commonly used for 
addresses and delay loop limits. They are entered directly in command mode. Using 
CODE stores numbers in less space than the 6 or more bytes used for floating-point 
constants. 


Number 

Code 

Entry Code 

0 

A0 

NOT PI 

1 

A1 

SGN PI 

2 

A2 

CODE “[3 ” 

3 

A3 

CODE “H ” 

4 

A4 

CODE “ B “ 

10 

B0 

CODE “ H ” 

11 

B1 

11 

12 

B2 

CODE “f’• 

20 

C0 

CODE “=” 

21 

Cl 

CODE‘ 

30 

D0 

CODE ‘2” 

50 

D1 

CODE“M” 

60 

D2 

CODE“W ” 

100 

D3 

100 

200 

D4 

CODE “COS’ 

500 

D5 

500 

1000 

D8 

1000 

4E4 

D9 

4E4 


In a program with a lot of numbers, as mine tend to be, this approach saves a huge 
amount of memory, as much as 10%. It’s worth the trouble of direct entering, which I 
undertake in entirety at this stage. (In fact, I don’t—the above coded skeleton, except 
for the C-loop, plus these and other standard data, are recorded on cassette for use 
whenever I start a new long program.) 






The use of directly entered data means that one must never use RUN (or CLEAR). 
To avoid the awful hazard of doing that in error, I always use GOTO 1 when using any 
program. 

Having dealt with the skeleton I must now start building up the main program routine. 
You see I’ve allocated only a few lines to this (1000 to 1090). (For FRENCH COUNT¬ 
DOWN that proves to be insufficient—showing that I don’t really follow my own rules 
too well.) Without a RENUMBER facility, which I tend not to like with any computer, 
that means cramped untidy line-numbers. Unless I run entirely out of line number space 
in a module, I try not to renumber by hand—it’s time-consuming and unimportant even 
if it does make for a neater listing. 

I’ve already dealt with box 3 in the flowchart, so let’s get stuck into box 4. The first part 
of this, 4a, is “get question”. As I said before, the procedure depends on how the 
question data are stored. By now I’ve decided to have sixty questions in the pool. 
Elsewhere in this book we describe different data structures—the obvious one to use is a 
set of directly entered arrays. However, there is an additional criterion to be satisfied, 
which precludes this—I want the data to be visible to the teacher/parent so that they can 
readily be changed. This means a set of sixty subroutines accessed by 

GOSUB QUEST + C0 * RND * D2 

and of the form 

LET P$ = “LE CHAT” 

LET Q$ = “THE CAT” 

RETURN 

May I also draw your attention to the fact that if arrays were used to carry the translation 
items a huge amount of memory would be wasted? This is because the string arrays 
would have to be dimensioned to enable the longest phrases to be held. (The same 
problem arose with ZEDTEXT.) If these are “LE PROFESSEUR” and “THE 
COUNTRY-SIDE” we would need 

DIM P$ (60,13) 

DIM 0$ (60,16) 

LET P$ (37) = “LE CHAT” 

LET Q$ (37) = “THE CAT ” 

and these two last lines alone would take 23 extra bytes. So, my method, as well as giving 
“teacher transparency”, saves some IV 2 K bytes, and gives another 10% reduction in 
saving/loading time. 
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So let's enter the data acquisition lines. 

1010 CLS 

1015 PRINT AT B0, A0; “TRANSLATE:” 

1020 GOSUB QUEST + 

INT (RND * D2 + Al) ♦ C0 • QUEST = 2000 QUEST: q section 
1025 LETT = INT (RND -I- .5) T: translation 

direction 

1030 IF NOT T THEN PRINT TAB A2; P$ P$: French phrase 

1035 IF T THEN PRINT TAB A2; Q$ Q$: English phrase 

1040 PRINT AT Cl, A0; “AFTER YOUR ANSWER, PRESS IENTERI 
3205 LET P$ = “TRISTE” 

3210 LETQ$ = “SAD” 

3215 RETURN 

Run it (with GOTO 1)—it works! Up come, ten times in rapid succession, 
“TRANSLATE/TRISTE” or “TRANSLATE/SAD”, with the ENTER message. 
Note that line 1020 isn’t being tested properly yet—whatever the random value given for 
the address, the micro arrives at 3205. (A useful trick there.) 

That leaves one tricky bit for the module of box 4—only allowing the subroutine to be 
accessed if it hasn’t been used before. What we need is a “flag” system. If each routine 
starts off with its flag at 0, and this switches to 1 when the routine is accessed, then we can 
test the flag and try again if it’s 1. Here, an array is definitely the structure to use. I’ll set 
up an array U (for “used”) with dimension 60; initialize each element to zero; put a line 
like LET U (N) = 1 in each data subroutine; and then test the flag. 

The initialization needs a subroutine of its own. Here it is: 


100 

GOSUB ARRAY • LET ARRAY = 1600 

ARRAY (1600) initialize 

array 

1599 

REM 1ARRAY 


1600 

DIMU(D2) 

U: subroutine used flag 

1605 

FORN = A1TOD2 

N: local counter 

1610 

LETU(N) = A0 


1615 

NEXTN 


1620 

RETURN 



Right—when the program firs^runs, all those flags will become 0. Try it—GOTO 1 (not 
RUN!), then PRINT U (Dl), U (A4) and so on. Then setting the flag: 

3200 LETU(D2) = A1 

And then testing for it (a bit of rewriting here): 

1018 LET N = INT (RND * D2 + Al) N: local value 

1019 IF U(N) THEN GOTO 1018 

1020 GOSUB QUEST + C0 ♦ N 

Get it? Fairly straightforward really. Want to look at the initialization chunk again? 
Simple—LIST ARRAY. There’s another advantage of named routines and sub¬ 
routines: you can list them by name rather than searching through for them. 

This is not going to be so easy to test though, unless you enter a special temporary test 




routine. That’s a bind and anyway we’ve got to get all those sixty sets of data in 
sometime. That I leave to you. You may not want a simple French vocab test anyway. 
What you’ve got to do, having worked out what data to test, is to set up 59 more 
subroutines like that in 3200-3215. FRENCH COUNTDOWN in fact has twenty each 
of nouns, verbs and adjectives, and lines like: 


1999 

REM [quest 1 

im 

REM 1 NOUNS 1 

im 

LETU(A1) = A1 

2925 

LET P$ = “LE GENDARME” 

2030 

LET Q$ = “THE POLICEMAN’ 

2035 

RETURN 

2040 

LETU(A2) = A1 

2415 

RETURN 

2419 

REM 1 VERBS ( 

2420 

LETU(C1) = A1 

2425 

LETP$ = “FAIRE” 

2430 

LETQ$ = “TODO” 

2435 

RETURN 

2440 

LETU(C2) = A1 

2815 

RETURN 

2819 

REM 1 ADJECTIVES 1 

2820 

LETU(41) = A1 


That gives a lot of testing to do—must check the data sometime. So, for the time being 
change the C-range in line 1005 to TO D2, and then GOTO 1, with an eagle eye on the 
screen and a talon ready on BREAK. After corrections, use CONT of course. That’ll 
keep you quiet for an hour or so. 

But, hold—if we’ve got twenty each of nouns, verbs and adjectives, can’t we get a 
menu going? Of course we can. Mind you, it’s going to mean messing about round 1020 
again. Still—it’ll be a nice feature. 

1. Set up menu, somewhere in the opening section ... 

405 GOSUB TITLE • TITLE = 800 TITLE: 800 

410 PRINT AT B0, A2; “I SHALL ASK YOU TEN 

QUESTIONS.” [Oops, correct 1005] 

415 LET A = D1 A: delay time 

420 GOSUB DELAY • DELAY = 500 DELAY: 500 

425 GOSUB TITLE 

430 PRINT AT A7, A2; “WHAT TYPE DO YOU WANT THESE”, 
“QUESTIONS TO BE?” 

435 GOSUB DELAY 
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440 PRINT ATB2, A2; ‘‘PRESS 1 FOR ... NOUNS.ATB4, A2; “PRESS2 
FOR ... VERBS”; ATB6, A2; “PRESS3 FOR ... ADJECTIVES 
AT B8. A2; “4 IS FOR A MIXTURE” 

445 IF INKEYS < “1’’ OR INKEYS > “4’’ THEN GOTO 445 

450 LET M = VAL INKEYS M: topic chosen 

That, an open subroutine by the way, calls two new service subroutines. I use DELAY in 
most programs. It causes execution to pause for a time set by the parameter A. Unlike 
the PAUSE instruction, which uses much less memory, it does not give rise to a screen 
flicker. Like it, though, it can be cut short at any time, by pressing ENTER in this case. 

Here’s DELAY: 

499 REM [DELAY 

500 FOR B = A1 TO A B: delay counter 

505 IF CODE INKEY$ = 118 THEN RETURN 

510 NEXTB 
515 RETURN 

Yes, you’re allowed two returns (or more) in a subroutine. 

And here’s TITLE, at 800: 

799 REM [title! 

800 CLS 

805 PRINT AT A1, A6; B$; AT A2. A6; A$; AT A3, A6; B$ 

810 RETURN 

This employs two directly entered strings—A$, the actual title, and B$, a row of inverse 
spaces to frame it. So put in A$ = “BFRENCH COUNTDOWN*”, with, note, inverse 
spaces at each end. Then B$ = “18 inverse spaces”. 

2. After all that convoluted rigmarole (sorry about it) we can LIST PROG and have a go 
at getting the value of M in use. 

1016 IF M = 4 THEN LET N = INT (RND * D2 + Al) 

1017 IF M <> 4 THEN LET N = INT (RND * C0 + Al) 

1018 IF M <> 4 THEN LET S = ((M - Al) * C0) S: data block 

1019 IF U(N + S) THEN GOTO 1016 

1020 GOSUB QUEST * (N + S) * C0 

3. Hang on, if you don’t see I’m doing there—there's another addition to make, in 

the initialization. No, don’t groan, it’s a little one! 

1001 LETS = A0 

Follow that lot through with care. It may seem convoluted, but I think it's fairly neat in 
the circumstances. (OK, if I’d had the idea of choice of topics before I'd started. I'd have 
come up with an easier way—but I didn’t.) 

If M is 1, 2 or 3, line 1018 gets us into the right block (value of S) and line 1017 selects 
the position in the block. If M is 4, S stays at0, N is in the full 1-60 range and GOSUB will 
put us in any part of the data section. This sketch may help. 
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1-20 


21-40 


41-60 


M= 1 
M = 2 
M = 3 
M = 4 


DATA 


ROUT 


I N E S 


S + N = 0 + (1 - 20) 

S + N = 20 + (1 - 20) 

S + N = 40 + (1 -20) 
S + N = 0 + (l-60) 


We now only have to deal with boxes 5-7 in the main program—checking if the answer’s 
correct and acting accordingly. Actually we’ve been having rather a heavy time, so we’ll 
do box 5 now with just a touch of 6 and 7 and then take a break. 

Because of the random choice of translation direction (lines 1025-1035) checking the 
correctness is not perfectly straightforward. The correct response is Q$ if T is 0 and P$ if 
Tisl.So: 


1045 INPUT R$ R$: response 

1050 IF R$ = “ ” OR LEN R$ < 3 THEN GOTO 1045 [mug-trap] 

1055 PRINT AT Cl, A0; E$; AT B2, A0; “YOUR ANSWER: TAB A2; R$ 
1060 GOSUB DELAY 

1065 IF (T AND R$ = P$) OR (NOT T AND R$ = 0$) THEN GOSUB RIGHT 
1070 IF NOT (T AND R$ = P$) OR (NOT T AND R$ = 0$) 

THEN GOSUB WRONG 


We’ve got some more direct data here. 

First, E$ is a whole line of spaces, used to wipe out the message printed in line 1040. 
The easiest way to get 32 spaces is to enter (directly) DIM E$ (32). We also have LET 
RIGHT = 550 and WRONG = 600. For the moment let’s not develop those two 
subroutines—we can just enter the following and test everything to date: 


549 

550 

599 

600 
645 


REM RIGHT 


PRINT,, “YES” 
REM I WRONG I 
PRINT,, “NO ” 
RETURN 


We’ll need to spend quite a bit of time perfecting those routines—but later, after the 
break I promised. 


GRAPHICS 


This program is getting quite good already, but it’s still only an automatic set-question- 
and-check-answer machine. The “countdown” in the title concerns the building and 
launch of a rocket-ship. Remember? So now, to make a change, we’ll go fairly fast 
through the graphics routines from line 5000. 

We have ten questions in our main C-loop. So there must be ten stages leading to 
launch, each stage calling on the predecessors, and the stage reached depending on the 
score. Part of the RIGHT/WRONG modules will in fact determine score and call the 
countdown routines. We’ll build the graphics up and test it bit by bit and as a whole. 
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Here’s the overall plan. 


4999 REM IGRAPHICSl 
Sm REM ISTAGE I 
5050 REM IGROUNDI 
5095 RETURN 
5100 REM [SKY] 

5105 GOSUB5050 
5145 RETURN 
5150 REM [GANTRY I 
5155 GOSUB5100 
5195 RETURN 
5200 REM [BASE I 
5205 GOSUB5150 
5245 RETURN 
5250 REM I STAGE 11 
5255 GOSUB5200 
5295 RETURN 
5300 REM ISTAGE2I 
5305 GOSUB5250 
5345 RETURN 
5350 REM ISTAGE 3! 

5355 GOSUB5300 

5395 RETURN 

5400 REM [clear GANTRY I 

5405 GOSUB5350 

5445 RETURN 

5449 REM [COUNTDOW] 

5450 CLS 

5455 GOSUB5400 
5495 RETURN 

5499 REM [LAUNCH] 

5500 GOSUB5450 
5545 RETURN 

Can you see the pattern? Each routine calls on the preceding one, which calls on the one 
before, etc, etc. By the time the score reaches 10 you’ll have given your subroutine stack 
a thorough work-out. This structure should be tested. Insert temporary lines like 

5055 PRINT “GROUND ” 

5110 PRINT “SKY” 
and so on 
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And then hold your breath and try direct entry: SLOW; GOTO 5500. You should see an 
awful mess of messages building up—but they should all appear in turn in the right 
positions. 

Now ril reproduce the designs I came up with, stopping only for really necessary 
comments. Try to see my short-cuts; run each subroutine when coded by a direct GOTO 
whatever. Do the testing in SLOW but code in FAST. For clarity gA means “graphics 
A”, etc, □ = space, ■ = inverse space, and boxes denote inverse video. 

1. Ground 

5055 FOR K = C0 TO D0 K: local counter 

5060 PRINT AT B9, K; “gA”; AT B8, K; “gA” 

5065 NEXTK 

2. Sky 

5110 FORK = C0TOD0 

5115 PRINT AT A0, K; “■”; AT Al, K; “■”; AT A2, K; “■” 

5120 NEXTK 

5125 PRINT AT A0, Cl; “ 0 AT Al, C2; “ 0 TAB C5; “0 
TAB C7; “ 0 TAB C4; “ 0 ” 

(It’s not worth putting those stars in at random or assigning them to a string.) 

3. Gantry 

5160 FORK = B7TOA5STEP-Al 
5165 PRINT AT K. Cl; “E]” 

5170 NEXTK 

5175 PRINT AT B1. C2; “[/]□”; AT A6, C2; “UHUC]” 

4. Base 

5210 PRINT AT B7, C3; “g8Dag5”; AT B6, C3; “g3Bg7g7Bg4”; 
ATB5,C4;“g8BBg5” 

5. Stage 1 

5260 FORK = AlTOA4 

5265 PRINT AT B5 - K. C4; “g8nng5” 

5270 NEXTK 

5275 PRINT AT B3, C5; “ Ig] [b] ”; AT Bl, C4; 

6. Stage! 

5310 FORK = AlTOA4 

5315 PRINT AT B1 - K, C5; “BB” 

5320 NEXTK 

5325 PRINT AT A9,C4;“gTBBgY” 
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7. Stage 3 

5360 PRINT AT A6. C5; “gRgE”; AT A5, C5; “g8g5”; AT A4. C5; “g3g4” 

8. Clear gantry 

5410 PRINT AT A6. C2; “□□□”; AT Bl, C2; “□□g8” 

5415 PRINT AT A6. Cl; “ 0 TAB Cl; “ (O) TAB Cl; “ 0 

TAB Cl: “ m TAB Cl; “ IT] TAB Cl; TAB Cl; “ (d] 

TAB Cl; “(Oj”; TAB Cl; “ ® ”; TAB Cl; “ [n] ” 


9. Countdown 

5460 PRINT AT B0. A3; “ ICOUNTDOWnI ' 

5465 PRINT AT B2, A7; “■■■■"; AT B3. A7; 

AT B4.A7; “■■■■” 

5470 FORK = AlTOA9 

5475 LET A = C0 [gives 1-second ticks] 

5480 PRINT AT B3, A9;B0-K 
5485 GOSUB DELAY 
5489 NEXT K 

5491 IF SC = B0 THEN GOTO 5497 SC: score 

5493 LET C$ = “ IHOLP] —NOT YET READY.” C$: for bottom line print 

5495 GOSUB BOTPR • BOTPR = 750 

5497 RETURN 

I’ve used a new routine here—BOTPR (bottom line print), one I’m rather proud of. It 
prints C$ on the bottom line of the screen, where the report codes go. Here it is. 


750 

LET X0 = PEEK 16396 -I- 256 * PEEK 16397 

X0: display start 

755 

FOR X = 761 TO 760 -I- LEN C$ 

X: bottom line site 

760 

LET YC = CODE C$ (X - 760) 

YC: character to plot 

765 

POKE X0 X. YC 


770 

NEXTX 


775 

RETURN 



What this does, in essence, is to POKE the right character from C$ into the right 
pigeon-hole in the display file (see Chapter 21). The routine is rather slow, and gives a 
nice change of pace from the usual printing speed. Do not try to mix it with SCROLL, 
however—I did that once and got the strangest effects —and made a whole long program 
(that I hadn’t recently saved) unworkable ... 

Anyway, it’s off to launch we go. But, alas, not to realize my dream of having the 
rocket zoom off into star-set. BASIC’s just too cumbersome. Here’s how the launch 
ended up—quite majestic actually, thanks to the vagaries of CLS after SCROLL. 

10. Launch 


96 


5505 PRINT AT B3. A8; ”0” 
5510 FORK = A4TOB7 



5515 PRINT AT K, Cl; [clear gantry] 

5520 NEXTK 

5525 PRINT AT B0, A3; “□□□□□□□□□□□□’’ AT B2, A7; 

TAB A7; “□□□□’’; TAB A7; “□□□□” 

5530 PRINT AT B6, C5; TAB C5; 

TAB C0; TAB C0; 

ATC0, C5; TAB C5; 

5535 FORK = A1TOD0 

5537 SCROLL 

5539 PRINTATCLC5;“**’’ 

5541 NEXTK 
5543 CLS 

(And here it would have been worth assigning ** to a string variable.) 

A lot of care’s needed with typing all that from a listing, so check it out properly—it’s a 
nice rocket, and it does take off. Remember: use SLOW; GOTO 5500 when you test the 
whole lot. 

POLISHING OFF THE MAIN ROUTINE 

After all that work outside the PROG section, you may expect a lot of amendments 
within it. But no, that’s the beauty of the modular approach. There’s no effect on the 
centre of the massive new building in the suburbs. 

In fact, we’ve almost finished the main routine now. All that’s left is to deal with the 
score (incrementing which is of course the function of the RIGHT subroutine). 

We need to initialize the score: 

1003 LETSC = A0 SC: score 

and we need to display it in the C-loop: 

1075 LET C$ = “YOUR SCORE SO FAR: ”+ STR$ SC+ 

“ OUT OF ”+STR$C 
1080 IFC<8THENGOSUBBOTPR 
1085 GOSUB DELAY 

And that’s the end of PROG! Recall that BOTPR is the routine for printing out on the 
bottom line the contents of C$. Note, by the way, how C$ is structured here, with the use 
of STR$ to convert a number to a string, and concatenation to join several strings into 
one. (Even in a PRINT statement, by the way, concatenation is neater than using the 
semi-colon. Thus PRINT A$ + B$ comes out more smoothly than PRINT A$; B$.) 

Just as well deal with 1099 REM I FINISH OFF I now, too. That should make us feel 
good, though there will still be a few oddments left. Here’s how I closed each run of 
FRENCH COUNTDOWN. 

1100 GOSUB TITLE 

1105 PRINT AT B0, A0; “YOU HAVE HAD YOUR TEN QUESTIONS. ” 
1110 GOSUB DELAY 

1115 PRINT,, “YOUR SCORE WAS ”;SC; “ 

1120 GOSUB DELAY 
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1125 IF SC = B0 THEN PRINT “WE HAVE I LIFT-OFF I —WELL DONE.” 

113<J IF SC < B0 THEN PRINT “THE COUNTDOWN IS ON I HOLD I . ” 

1135 IF SC < A5 THEN PRINT,, “YOU I MUST I LEARN YOUR WORDS.” 
1140 LETA = D4 
1145 GOSUB DELAY 

1150 COPY [“certificate”] 

1155 GOSUB TITLE 

1160 PRINT AT B0, A0: “LET SOMEONE ELSE HAVE A GO NOW.” 

1165 GOSUB OPEN • OPEN = 1500 OPEN [start routine] 

1170 GOTO START • START =D1 START [introduction] 

1175 REM lENDPROGl 

Nothing remarkable there—except to observe that I didn’t concatenate in line 1115. 
This was because I felt the resulting jerkiness was a bit more suspenseful. 

Here s the OPEN routine the above calls on. You may guess from its position that in 
truth I set it up earlier in the development process than now! 

1499 REM lOPENi 

1500 LET C$ = “TO TAKE I COMMAND I PRESS [ENtfiR] . ” 

1505 GOSUB BOTPR 

1510 IF INKEYS = “” THEN GOTO 1510 
1515 RETURN 

Bottom-line print again—yes, I am proud of it. And the standard wait-until-any-key- 
pressed, including ENTER/RETURN, in line 1510. 

RIGHT OR WRONG 

Now we come to the only remotely hairy bits left—developing the modules in sub¬ 
routines 550 and 600. These deal, you recall, with correct and incorrect responses 
respectively, boxes 7 and 6 in the flowchart. For a correct response, we need; 

(a) to add 1 to the score; 

(b) a suitable message; and 

(c) to build the rocket one stage further. 

I start off like this; 

550 LET SC = SC 1 [increment score] 

That’s (a) done. Trouble with “suitable messages” is that they can be rather gruesome if 
they don’t vary. So I decided to incorporate five suitable messages each for correct and 
incorrect responses, with random access to them. In this case we have the mini-module 
RTRES, a set of five subroutines; 

649 REM I RTRES I 

650 PRINT.. “ I GOOdI ” 

655 RETURN 

660 PRINT,, “ I right] , ” + N$ -I- N$; victim’s name 

665 RETURN 

670 PRINT,, “ ICORRECTI ” 




675 RETURN 

680 PRINT,, “ [YE^ . ” + N$ + 

685 RETURN 

690 PRINT,, “ IWELLDONE] ” 

695 RETURN 

Enter N$ directly for testing purposes at this stage rather than restricting the later 
development of the introduction. 

Now we can go on with RIGHT... 

555 GOSUB RTRES + B0* INT (RND * A5) 

560 GOSUB DELAY 

565 IF SC < A9 THEN PRINT,, “WAIT FOR STATUS”,, “CHECK. ” 

570 LETA = C5 

575 GOSUB DELAY 

580 IF SC <A9 THEN FAST 

585 IF SC > A0 THEN GOSUB STAGE + SC * D1 • STAGE = 5000 
590 SLOW 
595 RETURN 

OK? Nothing special there, I think. Oh, yes, the FAST/SLOW bit. In the early versions 
the rocket was always built up in SLOW— visibly. However, the early guinea-pigs 
rapidly got bored with that, and the FAST was introduced, except for COUNTDOWN 
and LAUNCH themselves. The STATUS CHECK message was used to prepare the 
user for FAST. 

Treatment of incorrect responses isn’t much different. No increment of score this time 
of course, but a few extra twiddly bits to make up. Here is the complete module. (If you 
don’t have a printer, disable the LPRINTcommands, i.e. ignore them!—though they do 
no harm.) 

600 LET U (N -I- S) = A0 [allows this question to be repeated] 

605 LPRINT P$, Q$ [prints out correct pair of phrases] 

610 GOSUB WRRES + B0 * INT (RND * A5) • WRRES = 700 

615 PRINT,, “THE ANSWER IS”,, TAB A2 
620 IF T THEN PRINT P$ 

625 IF NOT T THEN PRINT Q$ 

630 GOSUB DELAY 

632 IF SC < A9 THEN PRINT “WAIT FOR STATUS”,, “CHECK. ” 

634 LETA = C5 
636 GOSUB DELAY 
638 LET A = CODE “C” 

640 IF SC <A9 THEN FAST 

642 IF SC > A0 THEN GOSUB STAGE -I- SC * D1 

644 SLOW 

645 RETURN 

699 REM I WRRES 
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700 

PRINT,, “ SORRY, 

” + N$ + “ 

705 

RETURN 


710 

PRINT,, “1 THAT IS WRONG. 1 

715 

RETURN 


720 

PRINT,, “INOT so ’ 


725 

RETURN 


730 

PRINT,, ““ NO,NO|, 

’’ + N$ -1- ‘ 

735 

RETURN 


740 

PRINT,, ““[TAKECARE.]’’ 

745 

RETURN 



And all that should be quite straightforward. 


THE END 


The end is of course the beginning, the only bit we haven’t entered. I suggest that that is 
the right idea—leave the introduction, especially the instructions, until the rest of the 
program is spotless. I don’t think there’s anything at all special about the remaining lines. 
So I’ll just rush them off to you, and make one or two asides if need be. First the REMs: 


ERICDEESON (C) 1982 


And an aside already! You won’t want to enter that line, but you can’t anyway. 
Still—here’s how to do it. 


{a) Enter 1 REM IRIC DEESONI etc. (Did you know the Spectrum has a © key?!) 

(b) POKE 16510,0—this replaces the 1 with 0, so delete line 1. 

(c) POKE 16513,170—this replaces the REM with . 

(d) Note that the ZX81 can’t execute this line, another reason not to use RUN— 
if you do, you’ll get an instant report code! 


Anyway. . . 


10 REM I USE GOTO 50 NOT RU^ 
20 REM |T/S100016K| 

30 REM I PRINTER UTILIZED I 


[If you don’t own one, disable the 
LPRINT commands] 


And the introduction itself, with its own little bit of initialization first: 


60 LETA = C0 
100 GOSUBOPEN 
105 GOSUB TITLE 
110 GOSUB DELAY 

115 PRINT AT A5, A2; “DO YOU KNOW YOUR FRENCH WORDS? ” 

120 GOSUB DELAY 

125 PRINT AT A9, A2; “IF YOU DO, PREPARE FOR. 

“LIFT-OFF” 

130 GOSUB ARRAY [gives a few seconds’ delay too] 

349 REM I START MAInI 


100 








350 GOSUB TITLE 

355 PRINT AT B2, A0; “THIS IS MISSION CONTROL,’’; 

AT Cl, A0; “PLEASE TYPE YOUR NAME AND | ENTER | 

360 INPUT N$ 

365 PRINT AT Cl, A0; E$; AT B2, A0; “WELCOME TO THE 
LAUNCH-PAD,’’, N$; “” 

370 GOSUB DELAY 

375 PRINT AT Cl, A0; “PLEASE TYPE THE DATE, AND | ENTER I 
380 INPUT D$ 

385 PRINT AT Cl, A0; E$; AT B5, A0; “TODAY IS ’’ + D$ + 

390 GOSUB DELAY 

395 LPRINT A$,,N$,,D$ [headings of print-out—makes them jump!] 

. . . We’ve done the next bit 
455 CLS 

460 LPRINT “GROUPD”; M [print-out test choice] 

And that, my friend(s), is that. Le programme (yes, that’s what they call it!) est fini. 

By now, of course, you’ve forgotten my opening pages. But rest assured that I’ve tried 
to meet the criteria my cocktail-party friend needs: 

• effectiveness; 

• efficiency; 

• ease of use; 

• no computing knowledge required; 

• no doubts as to actions required; 

• carefully laid out, uncluttered, easy to read screen display; 

• enjoyment—well, hopefully. 

These were not in fact specifically educational criteria—I’ve also incorporated: 

• full test details and corrections on hard copy; 

• carefully determined (and varying) pace with delay-interrupt option; 

• full mug-trapping; 

• minimum predictability. 

Well, it’s helped me revise my French anyway. Et maintenant. . . 


DISTRIBUTION 

Having sweated many hours over a hot keyboard to produce an all-time masterpiece of 
useful programming, one’s mind naturally turns to the possibility of making the material 
available to a wider audience than one’s family or captive students. 

There are many ways of distributing software in the hope of rich rewards. (They 
include sticking an ad in the computer press, submitting the material to a so^are 
library, or finding a publisher for it.) Whichever one chooses, there is now an extra 
stage—that of preparing the distribution version. This stage involves several activities— 
before any of which it is essential to get a full LLISTing. These activities are: 

1. Removing REMs— to save memory/loading time and to make it harder for others 
to follow. 

2. Undertaking further techniques for cutting memory/loading time. 

3. Polishing the whole thing to impress anyone who sees the coding. 

4. Testing again, fully. 

5. Renumbering (if you’re keen), and testing again, fully. 





There are, then, two major differences between the master version of a program and the 
one distributed. The first, and more important, is the minimization of memory re¬ 
quirement. Removal of the REMs so necessary during development, and shortening 
variable names can, in particular, lead to a reduction of 10-15% in the length of the 
program and therefore in its loading and saving times. 

Another very significant saving can be achieved if the program incorporates arrays 
which are initialized during execution. It is short-sighted if such arrays have to be saved 
and loaded. Thus an array A (500) takes over a minute to transfer between micro and 
tape, even if it’s empty. So delete it before saving by using the direct command DIM 
A (1). As long as the program execution redimensions each array during initialization, 
this short-cut presents no problem. 

The second aspect of preparation for distribution is, I suspect, the more important to 
those folk who’re neurotic about copy-blocking. There is no way to stop pirates copying 
your programs. The method for copying any program is straightforward, but I shan’t give 
it here. (Potential pirates are invited to send me—er—$50 for the secret, if they promise 
not to tell anyone else.) All the same most people distributing software do make some 
attempt to make it harder to pirate. They may at least make the listing hard to 
disentangle (well, that’s the reason so often given for a cassette full of spaghetti), or they 
may prevent its being LISTed or LLISTed. If you are worried about this, best just 
“fingerprint” the program by including some dummy lines or directly entered combin¬ 
ation code. Then at least you can test a suspected rip-off to see if it bears your 
fingerprints. 


USING FRENCH COUNTDOWN 

There are two schools of considered thought about user documentation. (I say “con¬ 
sidered” because many people don’t seem to give the matter any thought at all.) On the 
one hand there are the suppliers who feel duty bound to provide sheaves of literature 
with their programs; few users can follow it, let alone find it relevant. On the other hand, 
there are the folk who reckon that their programs are self-documenting—and need no 
accompanying paper. I’m in the latter class. I have over 200 cassettes for the ZX81 alone 
(and as many again, in total, for the other computers I use). I find almost insurmountable 
the problem of storing accompanying paper so that it’s as accessible as the tapes. And 
there are few things in life more frustrating than wanting to use a good program and not 
being able to find the instructions. 

A fully self-documenting program must contain within itself all that the most in¬ 
experienced user is likely to need. That user is expected to know only how to get the 
software into the micro. So a program should be auto-RUN when loaded and should 
never lead to a report code. Ideally the BREAK key should be disabled—in practice, I 
mask it stiffly enough so that it’s very hard to actuate accidentally. Also the program 
should contain all necessary instructions. This takes up memory, of course—but that’s a 
great inducement to keep the instructions simple. (Alternative approaches some people 
use are to have the instructions saved as a separate program on the tape, or to put an 
audio commentary on the reverse.) I think FRENCH COUNTDOWN is fully self- 
documenting. Well, almost. So here are all the user instructions it needs ... 

French Countdown (9.8K) recorded on cassette at higher than normal volume for the 
1000 16K (printer optional). Valid for any student after some six months of a school 
French course, this is a game for testing simple English/French and French/English 
vocabulary. The user is invited to select nouns, verbs, adjectives, or a mixture, and is 
presented with a test sequence of ten translations. Each correct answer prepares a rocket 
further for launch; the rocket takes off if all ten questions are answered correctly. The 
printer outputs details of the user and the test, gives the correct vocabulary pairs for each 
question incorrectly answered, and reproduces the final score frame. The program is 
self-starting. Restart after BREAK with GOTO 50, not RUN. If delays are found to be 
excessive, speed them up using ENTER (which is coded I ENTER I throughout the 
program). 

Teachers may wish to change the vocabulary used. It is stored from line 2000. 

End of non-self-documentation. 
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We’ve been able to tackle some pretty serious problems in BASIC, and I’ve never 
actually said anywhere, “This would be a lot easier if we could tackle it in language X’’, 
although I may have thought that a couple of times. So why worry with machine code at 
all? Won’t it be much more difficult than BASIC? Is there anything to be gained? 

The first question is of course rhetorical. The answer to the second question is that 
machine code isn’t difficult to understand provided you have a clear grasp of the way the 
machine really handles data, and the form that the data take. The answer to the third is: 
“It depends.” Let me elaborate: 

There’s a Z80 microprocessor (actually a Z80A, but this makes no difference) at the 
heart of your 1000 which does the real computing donkey work. Unfortunately, it only 
responds to cryptic, and very simple, instructions written in—you guessed—its machine 
code. Any BASIC statement you want executed has first to be translated into this 
machine code, and that’s done by a program (itself written in machine code) called an 
interpreter, which sits permanently in the Read Only Memory (or ROM) chip of your 
computer. This translation process takes time, and it’s done every time the statement is 
executed. So if we bypass the interpreter, by writing directly in machine code, we get a 
dramatic improvement in speed. A program may run something like ten times faster! 
There are other reasons why speed improvements may be possible, but I’ll leave those till 
later. Of course, whether this increased speed is worth the hassle depends on what you’re 
trying to do. Some moving graphics displays may be hopelessly slow in BASIC. On the 
other hand, if you’re just waiting for an answer to some complicated problem to be 
printed, you may be quite happy to sit around for 20 seconds rather than 2. 

There can even be positive disadvantages to writing in machine code. A program can 
use more memory than its BASIC equivalent. (Again, we’ll see why later.) 

What I’m saying is that machine code is no cure-all. If s a tool, like any other, to be 
used in its proper place. If you’ve ever tried french-polishing a table with a chisel you’ll 
know what I mean. 
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A QUICK CHECK 


Since we’ll need to wade through a fair amount of stuff before we can write our own 
machine code and understand what’s going on, here’s a kind of converse to CHECK¬ 
OUT, which I call CHECK IN. Enter it exactly as listed. It starts with a weird REM 
statement that holds the machine code. 

1 REM E £ RND 7 X RETURN W C ii RETURN □ 4 PLOT 
Qg/ PAUSETAN 
10 POKE 16518,126 
20 PRINT 
30 FOR I = 1 TO 10 
40 PRINT TAB I -I- 5; “CHECK □ IN” 

50 PRINT 
60 NEXT I 

70 PRINTAT21,31;“ H5 ” 

80 INPUT G$ 

90 RAND USR 16514 

The only space that is input in the REM is marked; but the machine adds some spaces of 
its own. The underlined keywords RND, TAN require a function mode, and for 
RETURN, PLOT, PAUSE you must enter THEN, followed by the keyword, and erase 
the THEN using Delete. The graphics characters are graphic T and graphic A 
(characters 6 and 8 by code). 

Type RUN. You will get a display, and be asked for a character input. Hit ENTER. 
Fast, isn’t it? You’ll never get that sort of speed out of BASIC. The whole procedure 
probably looks more like magic than anything else, at this stage; but at least you should 
now be convinced that machine code does have some advantages. 



CHECKIN: Before. . . 
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. . . and after. 


You can safely change lines 30-60 to produce a different initial display—but do not 
omit line 70. For example, wipe out 30-^ and add 

30 LIST 

Experiment. What does the routine do? 

When you’ve finished this book, you’ll know that it’s not magic at all: in fact you’ll be 
able to write this kind of thing before breakfast. And you should be able to turn back to 
this page and answer three questions: 

1. How does CHECK IN work? 

2. Which program later in the book is it pinched from? 

3. Why won’t it work without line 70? 
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As I’ve told you before, the first thing is to 
understand the data structure. So what structure should 
numbers take in a machine code program? 


11 Numbers in Machine Code 


11 Numbers in machine code 

I said, a little while ago, that we were going to have to understand how the machine really 
represents data. Let’s start with that. 

We normally think about numbers in terms of tens. If I write the number 3814 we all 
understand that to mean: 

3 X 1000 + 8x 100+1x 10 + 4x1 

and we can see that to get a “place value” from the one on its right we simply multiply by 
ten. We say the number is in base ten. 

Because we’ve been doing this for as long as we can remember, it’s difficult to realize 
that there are other, perfectly sensible, ways of doing the same job. Early computer 
designers certainly didn’t; they used base ten representations in their machines and hit 
some nasty snags. Mostly, they were caused by the fact that electronic amplifiers don’t 
behave the same way for all the signals you want to input to them. For instance, an 
amplifier that is supposed to output double its input signal may well do so for inputs of 1, 
2,3 and 4 units; but then it starts to “flatten off’ so that an input of 5 produces an output 
of only 9.6, 6 produces 10.8, and maybe you can hardly tell the difference between the 
outputs for inputs of 8 and 9. 

Put a music tape in your cheapo cassette recorder and wind up the volume. Hear the 
distortion in the loud bits? It’s the same effect. 

Pioneer computer designers didn’t hear any distortion; they just found that the 
machines couldn’t distinguish between different digits at times, and that was hopeless for 
a computer. So they had to rethink their number representation to suit what the 
electronic gubbins would do best. 

The simplest thing you can do with an electrical signal is to turn it on or off; so you can 
represent the digits 0 (off) and 1 (on) satisfactorily. Distortion no longer matters. It’s 
clear whether a signal is present or not regardless of how mangled it is. But can we devise 
a number system which only uses 0s and Is? 

Yes. In a base ten number, the largest possible digit is 9. Add 1 to 9 and you get a 
carry has taken place. We can write any number using any other base we choose, and the 
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largest possible digit will always be one less than the base. If the base is 2, the largest digit 
is 1, so a base 2 (or binary) number only contains 0s and Is. 

What about the place values? In the base ten case we got those by starting at 1 (on the 
right) and multiplying by 10 every time we moved left one place. For a binary number we 
still start at 1, but we multiply by 2 every time we move left. 

So for instance the binary number 1101 can be converted to base 10 like this: 

110 1 

I -» X 1 -» 1 

I-> X 2 - 0 

I—!-> X 4 -> 4 

-^ X 8 - > 8 

= 13 


Converting the other way is easy as well; take 25 for example. If we write down the binary 
place values: 

32 16 8 4 2 1 

and work from the left, it’s clear that we need a 16, which leaves 9, and that’s made up of 
an 8 and a 1, so 25 is: 

0 110 0 1 

HEXADECIMAL CODE 


This is fine for relatively small values, but a bit messy for large ones. There are a number 
of quick conversion techniques, and there are binary-to-decimal and decimal-to-binary 
conversion program listings in Timex/Sinclair 1000: but I want to examine a procedure 
which makes use of hexadecimal code, because it will stand us in good stead later. 

A number in hex (nobody ever says “hexadecimal”, except me, just now) is a number 
in base 16. So the place values are obtained by successive multiplications by 16. The first 
five are: 

65536 4096 256 16 1 

“Hang about!” everybody’s saying. “Those are nasty numbers, and anyway, in base 16 
the largest digit has the value 15. Things are getting complicated.” 

Bear with me. We handle the problem of digits greater than 9 by assigning the letters 
A-F to the values 10-15. So the number 2AD in hex converts to decimal like this: 


2 A D 

I-> X 1 > 13 

-> X 16 -> 160 

-> X 256-> ^ 

= 685 


(D = 13) 
(A = 10) 


Now for the nice feature of hex. Because 16 is one of the binary place values (the fifth 
one) it turns out that each hex digit in a number can be replaced by the four binary digits 
which represent it. (By the way, “binary digit” takes almost as long to say as “hexa¬ 
decimal” so it’s normally abbreviated to “to”.) The table opposite shows the 
conversions: 
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Decimal 

Hex 

Binary 

0 

0 

0000 

1 

1 

0001 

2 

2 

0010 

3 

3 

0011 

4 

4 

0100 

5 

5 

0101 

6 

6 

0110 

7 

7 

0111 

8 

8 

1000 

9 

9 

1001 

10 

A 

1010 

11 

B 

1011 

12 

C 

1100 

13 

D 

1101 

14 

E 

1110 

15 

F 

nil 


A more extensive table is given in Appendix 1. 

Now suppose we want to convert 91W1 to hex. First we extract two 4096s, then some 
256s and so on like this: 

9041 

2 X 4096 = 8192 - 

849 

3 x 256= 768- 

81 

5x 16= 80- 

1 

lx 1 =_1^- 

0 


So the hex representation is 2351. 

Now we just copy the digit codes from the table: 

2 3 5 1 

0010 0011 0101 0001 

and that’s the binary equivalent of 9041; just run the four blocks together to get 

0010001101010001. 

The hex-to-binary conversion is so easy that, more often than not, we leave numbers 
in hex even when, ultimately, we need them in binary. After all, it’s easy to make an 
error in copying long strings of 0s and Is. 
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CONVERSION BY COMPUTER 


Here’s a program to convert from decimal to hex. It successively divides the number by 
16, looking at the remainder each time, so it extracts digits in the opposite order to that 
shown above. 

1 DIM HEX$ (4) 

20 LETP = 4 

30 LET HEX$ = “0000” 

40 PRINT “ENTER DECIMAL NO. (MAX: 65535)” 

50 INPUT DN 
60 LETN = INT(DN/16) 

70 LET HEX$ (P) = CHR$ (DN - 16 * N + 28) 

80 LETDN = N 
90 LETP = P-1 
100 IF DN>0 THEN GOTO 60 
110 PRINT “HEX VALUE IS”; HEX$ 

The result is always presented as a 4-digit number, with leading zeros if there are fewer 
than 4 significant digits. The program won’t work if the result should contain more than 4 
digits, but that’s ideal for our purposes, as we shall see. 

Here’s the code to convert in the opposite direction (hex to decimal): 

140 PRINT “ENTER 4 DIGIT HEX NO.” 

150 INPUT HEX$ 

160 LETDN = 0 

170 F0RP=1T04 

180 LET DN = DN * 16 -H (CODE (HEX$ (P)) - 28) 

190 NEXTP 

200 PRINT “DECIMAL VALUE IS:”; DN 
We could tie these routines together with a little menu: 

2 PRINT “DEC/HEX CONVERTOR” 

3 PRINT “1) DEC-> HEX” 

4 PRINT “2) HEX-> DEC” 

5 PRINT “3) END” 

6 PRINT “ENTER 1,2, OR 3” 

7 INPUTSEL 

8 IF SEL = 1 THEN GOSUB 20 

9 IF SEL = 2 THEN GOSUB 140 
10 IF SEL = 3 THEN STOP 

and, of course, we’ll need RETURNS at lines 120 and 210. 
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To deal with negative numbers, the machine uses a clever trick. 


12 Positive and Negative 


Now that we’ve seen something about manipulating binary numbers let’s return to 
looking at the way they are handled inside the machine. Usually, a number is held in a 
fixed number of bits, often 16 or 24 or 32, depending on the machine design. This 
number of bits is called the word size for the machine. 

Let’s examine what numbers could be held in a 4-bit word: 


4-bit pattern 

Decimal value 

wm 

0 

m\ 

1 

0010 

2 

0011 

3 

0100 

4 

0101 

5 

0110 

6 

0111 

7 

1000 

8 

1001 

9 

1010 

10 

1011 

11 

1100 

12 

1101 

13 

1110 

14 

nil 

15 


It’s obvious why bigger word sizes are chosen in practice; a machine which can only 
represent the numbers 0 to 15 is unlikely to be adequate. But there are two other 
problems; the notation can’t represent fractional values (7.14, for instance) and it can’t 
represent negative numbers. 


Ill 



We’ll ignore the fractions problem because most machine code routines only use 
integers, but the way in which negative numbers are dealt with is more pressing. 

The technique is simple: if you’ve got the binary representation of a positive number 
and you want to create its negative equivalent you do two things: 

1. Change all the 0s to Is and all the Is to 0s (this is rather picturesquely called 
“flipping the bits’’). 

2. Add 1 to the result. 

For instance, suppose you want —3. 

3 = 0011 in a 4-bit word 

Flipping the bits gives: 1100 
Now add 1: -f 1 

1101 

So 1101 represents —3. It’s called the 2*s complement of 0011. 

I’m not going to explain exactly why this works, but you can prove to yourself that it 
does in any particular case like this: 

If we add 3 to -3 (or 5 to -5 or anything to minus itself) we should get zero. So: 


0011 ( = 3) 

+ 1101 (= -3) 

= 10000 

111 (Don’t forget that 1 + 1=0 carry 1 in binary!) 

So we don't get 0000 at all; but the junior 4 bits are zero, and if we’re working in a 4-bit 
word the senior bit will just drop off the end. (For a convenient analogy, think about a 
car trip-meter with 3 digits; if it reads 999 and you drive an extra mile, it reads 000 and a 
“1” has “dropped off’ the left hand end). 

In other words we should have seen it like this: 
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This always works provided that the number of bits is fixed throughout. Don’t forget to 
include leading zeros to make up the number of bits to this standard length, before taking 
the 2’s complement. 

Let’s rewrite the 4-bit table of values, now including negatives: 


Decimal 

Binary 

2’s complement 

Decimal 

0 

0000 

0000 

0 

1 

0001 

nil 

-1 

2 

0010 

1110 

-2 

3 

0011 

1101 

-3 

4 

0100 

1100 

-4 

5 

0101 

1011 

-5 

6 

0110 

1010 

-6 

7 

0111 

1001 

-7 

8 

1000 

~i 1000 

-8 

9 

1001 

0111 

-9 

10 

1010 

0110 

-10 

11 

1011 

0101 

-11 

12 

1100 

0100 

-12 

13 

1101 

0011 

-13 

14 

1110 

0010 

-14 

15 

nil 

0001 

-15 


Straight away we see that there’s a problem; every bit-pattern occurs twice so that, for 
instance, 1001 could mean 9 or -7. So we’ll have to restrict the range of values still 
further. I’ve drawn a dotted line around the region we actually choose to represent. If 
you look at the senior (leftmost) bit in each of the patterns you’ll notice that it’s “0” if the 
number is positive and “1” if the number is negative. This is obviously a very convenient 
distinction. 

So the range of numbers we can get into a 4-bit word is -8 to +7. For 5 bits it would be 
-16 to +15. For 6 bits it will be -32 to +31 and so on. 

A 16 bit word (which is important so far as the 2^0 is concerned) holds the range 
-32768 to +32767. A table of 2’s complement notations for 8-bit words is given in 
Appendix 1. 
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It’s easier to start with a simplified, imaginary machine. The Z80 
is like this, but more complicated: get the main ideas here! 


13 Machine Architecture 


That’s enough about numbers. Now we’ll look at how the machine crunches them. To do 
this, we need to know about the internal structure of the processor—its architecture. 

Now, the Z80 processor is the product of some twenty-five years of computer develop¬ 
ment and is a fairly sophisticated beast. So it’s not really a good place for the beginner to 
start. What I’m going to do, then, is describe a simple processor which might have been 
built in the late 1940s (except it wasn’t), just to introduce the important concepts which 
are relevant to virtually all current devices, without having to worry about the frills, 
which we can look at later (in chapters 16 onwards). 

We’ll suppose that our imaginary machine has a memory of 16-bit words and a number 
of 16-bit special-pur]x>se registers as shown below: 




m 

m\ 

m 

m 

004 

005 

006 

007 

008 

009 

00A 

00B 


addresses 


Let’s look at the memory first. In BASIC we could have called each of those memory 
locations anything we fancied, but the naked machine isn’t so friendly. It insists on 
numbering every location in an absolutely fixed way, starting at zero, as I’ve shown. 
These numbers are called the memory addresses, and I’ve numbered them in hex. 
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although you should always bear in mind that, ultimately, the coding will be binary. 

What can be held in a memory word? Well, any pattern of 16 bits. Obvious; but the 
point I’m driving at is that those 16 bits can mean anything we want them to mean. If we 
want them to mean a 2’s complement coded integer then a word holds a number in the 
range —32768 to 32767. If we want them to mean a positive integer with no sign bit then 
the number is in the range 0 to 65535. If we want, we can split the word into two 8-bit 
fields each of which represents an alphabetic, punctuation or graphics symbol. As 
Tweedledee (or was it Tweedledum?)* said: “When / use a word, it means just what I 
choose it to mean—neither more nor less.” I sometimes think Lewis Carroll was ahead 
of his time. 

Now for the special-purpose registers. Just the A-register to kick off with. This is used 
every time you do any arithmetic. The result of any sum you ask the machine to do is put 
into the A-register. (Sometimes it’s called the accumulator, by the way.) Most arithmetic 
operations work on two values; it’s no good asking the machine to work out 3-I-, you 
need to say what 3 is to be added to. One of these values must be in the A-register before 
the addition operation is executed. So you can write an instruction like: 

ADD (1A3) 

and the machine takes that to mean: 

1. Add the contents of memory location 1 A3 to the contents of the A-register. (The 
brackets round 1 A3 are being used to indicate that it’s the contents of 1 A3 and not 
the number 91 A3 which is to be added.) 

2. Put the result back in the A-register. 

We’ve just written our first machine level instruction. It’s not actually in machine code, 
but it’s close. Look at its general form. It consists of an operation code, ADD, and an 
address, (1 A3). Many instructions will look like that. Incidentally, life is too short to say 
“operation code” too often; everybody shortens it to opcode. 


AN ADDITION PROGRAM 

Let’s think about a sequence of machine instructions which would model the BASIC 
statement: 

LETR = B + C 

First we would have to assign actual addresses to R, B and C. Suppose that these are 
103, 104 and 105, respectively. We have to get the contents of 104 into the A-register. 
Let’s invent an LD (for load accumulator) instruction to do this: 

LD (104) 

then add on the contents of 105 
ADD (105) 

and finally we need a way of storing the A-register’s contents back in 103. So we’ll invent 
a “store” instruction: 


ST(1(»3) 

Now we have a simple machine level program consisting of 3 instructions: 

LD (104) 

[load B into A-register] 

ADD (105) 

[add on C] 

ST (103) 

[put the result in R] 


How do we get the machine to run such a program? 


See page 152. 
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We’re used to the idea that a program is stored in the machine before it’s executed. 
After all, if you wrote the BASIC statement: 

10 PRINT “HELLO WORLD” 

you’d be somewhat disconcerted if, as soon as you hit ENTER, the message “HELLO 
WORLD” were displayed. You expect it to be held until you need it. So, by the same 
token, a machine level program has to be stored first. Where more natural to store an 
instruction than in a memory word? (A word means what you want it to mean— 
remember?) Of course, that implies that the opcodes LD, ADD and so on have to be 
coded as bit patterns, but all we have to do is invent a table of bit patterns in a quite 
arbitrary way like this: 


Opcode mnemonic 

Binary code 

ADD 

am 

LD 

mi 

ST 

0010 


and every time we think of a new opcode that’s needed, we add it to the table. 

I’ve assumed, above, that all opcodes have a 4-bit binary code. That allows 16 
different patterns and therefore 16 distinct instructions. This is a small instruction set by 
modem standards but it will do for our hypothetical toy computer. We’ve got 16 bits in 
the word altogether, so 12 are left for the address portion of the instruction. 

So LD (104), once inside the machine looks like: 


00011000100000100 




opcode address (104 hex converted to binary) 


Once you’ve seen one bit pattern, you’ve seen them all, so from now on we’ll write the 
hex versions of instructions. It’s marginally less tedious. 
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THE PROGRAM COUNTER 

Suppose we store our 3-instruction program from location 0FF onwards: 

0FE 
0FF 
100 
101 
102 

103 

104 

105 

106 

Now we need a way of saying to the machine: “Kick things off by executing the 
instruction in 0FF, then do the one in 100, then one in 101.” That’s what the PC-register, 
or program counter, is for. It acts as a kind of bookmark for the computer. We run the 
program by initializing the PC to the address of the first instruction. While the machine is 
obeying this instruction, the PC is automatically updated by 1, so that when the system 
returns to examine the PC, it will go and obey the next instruction, and so on. 

There’s a snag, though. While the last instruction (in 101) is being dealt with, the PC 
will be updated by 1 as usual, and so when the machine looks at it again, it will find 102, 
and leap off to execute the instruction there. What instruction? We didn’t put one in 102. 
Ah! But there has to be a bit-pattern in 102 left by a previous program, or just set up 
when the machine was switched on. So the machine will interpret this pattern as if it is an 
instruction, because that’s what we’ve asked it to do. And then it will roll on through 
locations 103,104 and 105 and that’s where we’re storing data! So if the number in 104 is 
20FF, for instance, the machine will interpret this as: 

ST (0FF) 

which will copy the contents of the A-register into 0FF, thereby destroying the first 
instruction of our program! Obviously what we need is a “halt” instruction (I’ll use the 
mnemonic HLT) which stops the updating of the PC in its tracks. So the program now 
reads: 

LD (104) 

ADD (105) 

ST (103) 

HLT 

There’s an important point here. Precisely because we are using words to mean different 
things at different times, we have to keep a very careful eye on the implications the 
machine will draw from what we tell it to do. If we request it to ADD the contents of a 
location to the A-register, then it will assume that that location holds a number. It will 
rnake no tests; it cannot—any bit-pattern could represent a number. Similarly, any 
bit-pattern could represent an instruction, so if the PC points to a location, its contents 
will be executed as an instruction. 

The rule is: keep data and programs firmly apart. If you don’t you can expect to be 
totally mystified at regular intervals. As I’ve indicated, a whole program can disappear 
without trace while it is running! 
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Some more instructions: the functions of the program counter 
and the stack. 


14 Jumps and Subroutines 


So far, our instruction set looks a bit thin. We’ve got LD and ST, which will move things 
around memory, ADD, which is pretty primitive arithmetic, and we can stop things with 
HLT. 

We’ll pep up the arithmetic capability a bit by adding SUB, which will subtract the 
contents of a location from the A-register, but that’s all we’re getting. No multiply, no 
divide, definitely no square root. 

What we really need is a set of branch instructions, equivalent to BASIC’s IF ... 
THEN... 


JUMPS 

It’s going to b>e fairly easy to branch to an instruction out of the usual sequence; what we 
need to do is change the contents of the PC. So we’ll use an instruction like: 

JP416 [jump to 416] 

Whenever it is executed, it will put 416 in the PC. The system is “fooled” into thinking 
that the next instruction is in 416, and then it will go on to 417, 418 etc. until the next 
“jump” instruction is encountered. Of course, any address can follow the JP opcode. 

This instruction is more like a GOTO than an IF ... THEN .... What we need is an 
instruction which resets the PC only if some condition is met. The simplest test we can 
make is whether the A-register contains zero. 

JPZ 2A7 [jump to 2A7 only if A-reg. contains 0] 

Another would be: 

JPN 14E [jump to 14E only if contents of A-reg. are negative] 

That’s the minimum we can get away with, because we can now test for a positive 
(non-zero) number by noticing when the program doesn’t jump on either JPZ or JPN 
instructions. 


SUBROUTINES AND STACKS 

While we’re on the subject of transferring control from one place to another inside the 
program, how about something like BASIC’s GOSUB and RETURN? 

We’ll have an instruction: 

CALL 205 [call the subroutine starting in 205] 

What does it do? Well, obviously it puts 205 into the PC, but we could use a JP for that. 
CALL performs a second function: it stores the address of the instruction after the 
CALL, so that when a “return” (opcode: RET) is encountered it can load the stored 
address back into the PC to continue the main program from where it left off. This is 



where the SP register comes in. We use some of the memory as a stack (remember 
stacks?) and SP points to the top of the stack. When a CALL is obeyed, the return 
address (the address of the CALL + 1) is pushed on to the stack. When the RET is 
encountered the stack is popped into the PC. Here’s an example: 



3B9 

3BA 

3BB 

3BC 

3BD 

3BE 


subroutine 


3FD 

3FE 

3FF 


3B9 

3BA 

3BB 

3BC 

3BD 

3BE 


subroutine 


3FD 

3FE 

3FF 

The program steps through th< 


3B9 

3BA 

3BB 

3BC 

3BD 

3BE 


subroutine 


3FD 

3FE 

3FF 


and control is back inside the main program. 






The private eye tracks his victim: how to use the contents of one 
address to point to another one. 


15 Indirection and Indexing 


There are only two registers left to talk about, and both have similar functions: they can 
both alter the address part of an instruction while the program is running. 

INDIRECTION 

Let’s look at the way the I-register does this first. We’ll invent a new opcode, LDI or 
“load indirect’’. Like HLT, it doesn’t have an address associated with it. To the machine, 
it’s just like an LD except that the high bit of the address field is set to This bit is 
called the indirection flag, and simply indicates to the machine that indirection is in force. 
So the binary form of the LDI instruction is: 


0001100000000000 


opcode 




“ 1 ' 

address (not used) 
■— indirection flag 


The hex code is 1800. When the machine encounters this instruction, it uses whatever 
number is in the I-register as the effective address. So if the I-register contains 1E4 and 
an LDI instruction is executed, the effect is exactly the same as if the instruction had 
been LD 1E4. In other words the I-register acts as a memory pointer, and we can move it 
around to our heart’s content if we can do arithmetic with it. That means moving values 
into the A-register, because that’s the only place we can do arithmetic. So we’ll invent an 
opcode XAI for “exchange contents of A-register with contents of I-register’’. 

Of course, the indirection flag can be set for any instruction which has an address part. 
So we can have STI, JPI, ADDI etc. and in each case, the last 3 digits of the hex code will 
be 800. 


AN EXAMPLE 

Let’s look at an example which uses these ideas. Suppose that we want to initialize a ID 
array of length 20, to hold the numbers 2, 4, 6, 8 . . . 40. In other words we want a 
machine code equivalent of the BASIC: 


120 


FORC= 1TO20 
LETA(C) = C*2 
NEXTC 




There are a series of values which are going to have to be in memory somewhere, to 
make this work. They are 1 (because the loop count goes up in ones), 2 (because that’s 
the increment for the array contents) and 20 (which is needed to test for the end of the 
loop). I don’t, for the moment, want to be bothered with exactly where these numbers 
should be stored, so I’m going to allow addresses to be referred to temporarily by names 
(just like BASIC names). We’ll have to convert these to numbers when we finally get to 
machine code, of course. This is an application of Jones’s First Law of Computing: 
“Never put off till tomorrow what you can put off till the day after. ” So we’ll assume that 
the numbers we want are available in locations called Nl, N2 and N20. Similarly, we’ll 
have a location called BASE which holds the address of the first element of the array, 
and one called COUNT which will act as the loop counter. 

First we set the I-register to point to the base of the array: 

LD BASE 
XAI 

Then we set the COUNT to 1: 

LD Nl 
ST COUNT 

Now we double this (by adding it back into the A-register) and store it in the location 
pointed at by the I-register. (We talk about “storing through the I-register’’ for short.) 

ADD COUNT 
STI 

We “undouble’’ the value on the A-register again, subtract 20 and see if the result is 
zero. If it is we’ve finished: 

SUB COUNT 
SUB N20 
JPZ OUT 

OUT is another, as yet unspecified, address. We don’t know where it is yet, because 
we don’t know where the program ends, and so, again, it’s useful to give it a name 
temporarily. 

If the branch doesn’t occur, we add 1 to the COUNT: 

LD COUNT 
ADD Nl 
ST COUNT 
and increment the I-register by 1: 

XAI 

ADD Nl 
XAI 

The current COUNT is now back in the A-register, so we can loop back to the doubling 
operation: 

IP LOOP 

provided we give the “ADD COUNT’’ instruction the symbolic address “LOOP”. Let’s 
do this by preceding the instruction by its symbolic address followed by a colon: 



LOOP: ADD COUNT 

We can do the same sort of thing to set up the initial values we need, by defining a new 
opcode HEX which just sets a word to a required value. It isn’t really an opcode at all 
since it isn’t equivalent to a machine instruction, so we call it a pseudo-operation. The 
whole program looks like this (ignore the numbers in the left- and right-hand margins for 
the moment): 


m 

LD 

BASE 

1 033 

021 

XAI 


A 000 

022 

LD 

Nl 

1 030 

023 

ST 

COUNT 

2 032 

024 L(X)P: 

ADD 

COUNT 

0 032 

025 

STI 


2 800 

026 

SUB 

COUNT 

4 032 

027 

SUB 

N20 

4 031 

028 

JPZ 

OUT 

6 047 

029 

LD 

COUNT 

1 032 

02A 

ADD 

Nl 

0 030 

02B 

ST 

COUNT 

2 032 

02C 

XAI 


A 000 

02D 

ADD 

Nl 

0 030 

02E 

XAI 


A 000 

02F 

JP 

LOOP 

5 024 

030 Nl: 

HEX 

0001 

0 001 

031 N20: 

HEX 

0014 

0 014 

032 COUNT: 

HEX 

0000 

0 000 

033 BASE 

HEX 

0000 

0 000 


The only symbolic address which doesn’t appear in the left-hand column, and is there¬ 
fore still unspiecified, is OUT. We’ll worry al^ut it later. 

The form of the program we now have is written in what is known as assembly code. 
On modem sophisticated computers there will be an assembler program whose function 
is to convert this into real machine code for us. 


HAND ASSEMBLY 


Alas, neither our hypothetical machine nor the 1000 has such a program. So we have to 
do the job by hand. We need a table of opcodes and their equivalent hex values: 
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Opcode 

Hex 

ADD 

9 

LD 

1 

ST 

2 

HLT 

3 

SUB 

4 

JP 

5 

JPZ 

6 

JPN 

7 

CALL 

8 

RET 

9 

XAI 

A 


Also we need to know where the beginning of the program is. That’s a more or less 
arbitrary decision, so let s assume it’s at 020. Since each instruction occupies 1 word, we 
can write down the address of each instruction. You’ll see that I’ve done this down the 
left-hand side of the program. Now we can replace the opcodes and addresses by their 
hex equivalents. For instance, LD BASE becomes 1033, since BASE is now identified as 
033. The right-hand margin shows the complete code. 

The only instruction which needs further comment is JPZ OUT, which encodes as 
6 047. Why should OUT be at 047? It could be elsewhere, but 047 is the first location it 
can be at. The reason is that the array is occupying the space from 033 to 046 (twenty 
words), and we obviously don’t want to go clumping around inside the program’s data 
area. 


THE INDEX REGISTER 


When the X-register is in use, the real instruction address is formed by adding the 
address field to the contents of the X-register. For instance, if the X-register contains 
400, then the instruction LDX 005 has the same effect as LD 405. 

We’ll pinch another bit of the address field to indicate when indexing is in operation, 
so the LDX 005 instruction looks like this: 


000l|0|l|000 0 0 0 0 1 0 1 


opcode 


-f- 

address 


^ index flag 


indirection 

flag 


In hex, that’s 1405. 

Actually there’s nothing you can do with indexing that you can’t do with indirection. 
It s just that it will do arithmetic with addresses automatically instead of leaving the job 
to you. 
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The actual architecture of the Z80 CPU, the heart 
(or is it the brain?) of your ZX81, T/S 1000 or Spectrum 


16 AtlasttheZSO! 


I m sorry that you’ve had to wade through the last ten or so pages without being able to 
try anything out, but if you’ve really understood the ideas in them, you’ll find that 
understanding the Z80 is a breeze. 

Before we get into the Z80’s architecture (sorry, the chapter heading isn’t quite 
accurate!) let’s consider some of the difficulties of the processor I’ve just described. 

First, the 4-bit operation code only allows 16 different instructions. (OK, we cheated a 
little, by allowing the indirection and indexing flags to spill over into the address field, 
but that in turn means we’ve limited the address size, and therefore the maximum size of 
memory!) The Z80 has 694 instructions! To give each of them a separate bit pattern 
means that we need an 8-bit field (1 byte); and even then some fudging is needed. 

Second, our imaginary machine uses memory in a rather careless way. Some of the 
instructions don t use the address held (HLT, LDI, STI, for instance), so a sequence of 
such instructions wastes 10 bits in every word. The 2^80 gets over this problem by 
allowing different instructions to have different lengths. Some instructions have no 
address field and are just 1 byte long. Others have a 1-byte address field and so are 2 
bytes long. Others have a 2-byte address field for a total of 3 bytes. There are even some 
which have 2-byte opcodes! This means that the PC can’t increment by 1 for every 
instruction executed. It has to increment by the length of the instruction. 

Third, we always have to handle 16-bit words, which is inconvenient if we’re dealing 
with characters (which normally occupy a byte each). So it would be nice to allow 8-bit 
and 16-bit operations. 

Fourth, the fact that there is only one general-purpose register (the A-register) can be 
annoying. It often means that intermediate results have to be stored temporarily back in 
memory while some other calculation is done. The Z80 has a number of general-purpose 
registers; although, as we shall see, exactly how many there are varies depending on what 
we’re using them for. 
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THE REGISTERS 

Here’s the register organization: 


8 bits 8 bits 


A 

F 

B 

C 

D 

E 

H 

L 


8 bits 8 bits 


A' 

F' 

B' 

C' 

D' 

E' 

H' 

V 


general- 
— purpose 
registers 


main set 


alternate set 



special- 
— purpose 
registers 


16 bits 

Ignore the alternate set for the moment. 

T^e registers appear in pairs, indicating that they may be used either as 8-bit or 16-bit 
registers. For instance, we can refer to the B-register (8 bits), or the C-register (8 bits) or 
the BC register (16 bits). The B, C, D, E, H and L registers can all be used in this way (in 
pairs BC, DE, HL only) but the A and F registers are strictly 8-bit registers and cannot be 
combined. For the 16-bit pairs, the senior byte is the left-hand one (B, D, H) as you’d 
expect. 

There are two index registers, the IX and lY, a stack pointer (SP) and program 
counter (PC). What, no indirection? Actually any of the 16-bit general-purpose register 
pairs (BC, DE or HL) can be used for indirection but, for simplicity, we shall always use 
the HL for this purpose. 

There are two sets of instructions, one for handling 8-bit operations and the other for 
handling 16-bit operations. We’ll start with the 8-bit “load” instructions. 


125 






How to shuttle data from one place to another . . . 
and a few words about addressing modes. 


17 Load 


Let’s look at the “load” (LD) operation as an example of the 8-bit group. It’s very like 
the LD instruction in our imaginary machine, except that two extra addressing modes 
are allowed: register-to-register, and immediate. That gives a total of five, with direct, 
indirect and indexed available as before. 

1. Direct addressing 

This looks much the same as our imaginary equivalent, except that, since there is 
more than one register, we have to specify which register we want loaded: 

LD A, (0F1C) 

This loads the contents of 0F1C into the A-register. Note that, by convention, the 
movement is from right to left, so that we can write: 

LD (0F1C), A 

and mean “copy the contents of the A-register into 0F1C”. 

(Actually, the A-register is the only 8-bit register which can be directly 
addressed.) 

2. Indirect addressing 

Again, this is straightforward. Since we’re going to standardize on the HL for 
indirection, the instruction format is: 

LD A, (HL) 

which means “load the A-register through (i.e. from the address contained in) the 
HL register”. To pass data in the opposite direction we could have: 

LD (HL), A 

which puts the contents of A into the address contained in HL. (For this in¬ 
struction, registers other than A are allowed.) 

3. Indexed addressing 

Here, we need to indicate which index register is in use, and the amount of the 
offset: 

LD A, (IX + 2E) 

Note that in direct addressing, I showed an address of 4 hex digits, because 16 bits 
(2 bytes) are allowed for the address. The offset value in an indexed address 
instruction must be held in 1 byte, however, so I’ve only shown two hex digits. 


126 



4. Register-to register 

We can transfer data between registers like this: 

LDD,B 

which means: “load the contents of B into D“. 

5. Immediate 

Here, data itself, rather than the address of data, is placed in the address field. So 
we can write: 

LDB,07 

to mean “put the number 7 in B”. Note again that the number is two hex digits, 
since it has to be stored in the single byte of the B-register. Note also that a “LD“ is 
really a copy : the numbers are retained in their original addresses or registers, but a 
copy is placed at the destination. 

HEX CODES 

Now let’s see what each of these instructions looks like in hex; for a full listing see 
Appendix 5. 

1. LDA,(0F1C) 

First we look up the opcode for the LD A, (nn) instruction. (The nn indicates a general 
2 byte address). Tliis is 3A. So you would expect the instruction to code as: 

3A0F1C 

Unfortunately, there’s a slight complication caused by the way the 7^ thinks about 
numbers; it likes the least significant (junior) byte of an address first. So we have Xoswap 
the address bytes round: 

3A 1C0F 

This is mildly annoying, but you soon get used to it. It is an invariable rule for 2-byte 
numbers in Z80 instructions: junior byte first, then senior: hence all those PEEK X + 256 
* PEEK (X l)’s in the Timex Manual. 

The LD (nn), A instruction has the code 32, so: 

LD (0F1C) becomes 32 1C 0F 

2. LDA,(HL) 

This is easy. There is no address part so it’s just a 1-byte opcode. Look it up and you’ll 
find it’s 7E. 

Similarly LD (HL), A codes as 77. 

3. LDA,(IX + 2E) 

The general instruction is LD A, (IX + d), d indicating a 1-byte displacement (in 2’s 
complement notation), and its code is DD 7E. (Note that—a 2-byte opicode!) So the 
instruction is: 

DD 7E 2E 

where the byte 2E is the displacement chosen in this case. 

4. LDD,B 

No problem here, again. The code is 50. 

5. LDB,07 

The opcode is 06 so the instruction is 06 07. 



To kick off with, here’s a machine code program to add two 
numbers—and a simple BASIC loader to write and run 
machine code easily. 


18 Arithmetic 


What about arithmetic? There’s an ADD and a SUB instruction, both of which re¬ 
ference the A-register, and which may use any of the addressing modes except direct. 
So let’s try writing a program to add the numbers 4 and 7 together. This would work: 

LD A, 04 [put 4 in the A-reg.] 

LD B, 07 [put 7 in the B-reg. ] 

ADD A, B [add them, and put the result in the A-reg.] 

Now store the result away somewhere: 

LD (4300), A 

Here’s the program, the hex code, and the decimal equivalent: 


Program 

Hex 

Decimal 

LDA.04 

3E(W 

6204 

LDB,07 

0607 

0607 

ADD A, B 

80 

128 

LD (4300), A 

320043 

500067 


LOADER 

We’re left with the problem of loading this code into the 1000, and then executing it. 
Since we’re going to do a number of machine code routines, it’s going to be worthwhile 
writing a BASIC program which loads and then executes machine code. 

This is fairly easy. In principle, all we need to do is to ask the user where he wants to 
put the code in memory, then ask for each byte of code in turn, and POKE it into the 
appropriate location. TTien we run the program by calling the USR function. Finally, we 
PEEK all the program locations and data area to ensure that the program is still intact 
(remember, it’s possible to overwrite a program by accident) and that the results are 
correct. Obviously, it makes sense to have the data and program areas adjoining. So 
we’ll adopt this convention: the data area always precedes the program area, and is 
loaded with zeros to start with. So we’ll begin by asking the user the size of his data area 
(as a number of bytes). 
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There’s one other problem; according to the Timex Manual all routines called by USR 
have to end the same way: 


LDA. IE 
LD I. A 
LD lY, 4m 
RET 


3E1E 
ED 47 
FD 21 00 40 
C9 


62 30 
237 71 
253 330064 
201 


(Actually it’s that final RET that is crucial.) We call this the standard ending. So we 
might as well make the program generate this code at the end of the routine auto¬ 
matically. Here’s the loader in its simplest form. (In IK you can save memory by 
shortening the PRINTed phrases.) 


10 PRINT “BASE ADDRESS:D ”; 

20 INPUTS 
30 PRINTS 

40 PRINT “NO. OF DATA B’VTES: ; 
50 INPUT D 
60 PRINT D 
70 FORI = 0TOD-1 
80 POKES -I- 1.0 
90 NEXT I 
100 LETA = B-I-D 
110 PRINT “CODE: ” 

120 INPUT C 

130 IFC<0THENGOTO180 

140 PRINT C 

150 POKE A. C 

160 LETA = A + 1 

170 GOTO 120 

180 CLS 

190 F0RI=1T09 
200 POKE I - 1 -I- A, M (I) 

210 NEXT I 
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The last three lines assume that the array M has been set up in command mode (i.e. 
without line numbers) by: 

DIM M (9) 

LETM(1) = 62 
LET M (2) = 30 
LET M (3) = 237 
LET M (4) = 71 
LET M (5) = 253 
LET M (6) = 33 
LETM(7) = 0 
LET M (8) = 64 
LET M (9) = 201 

(These are the standard “end of routine” codes mentioned above). 

Or, you could input these values into M using a FOR loop, and then delete the loop 
before saving. It’s probably just as longwinded. though. Either way, don’t forget to 
execute the program with GOTO 10 and not RUN, so that the array values are 
preserved. 

Now we must execute the program: 

220 LETY = USR(B + D) 

(Don’t forget that B + D is where the program begins. Before that there’s just data). The 
value, here Y. returned by USR isn’t usually needed, but it has to be there to satisfy the 
syntax of the statement. It actually contains whatever was in the BC register pair on 
returning from the machine code routine. 

Finally, we look at the state of the program and its data: 

230 FORI = BTOA + 8 
240 PRINT I. PEEK I 
250 NEXT I 


RUNNING 

Now, to run the program. Firstly, the machine code routine has to coexist with the 
BASIC system. If we’re careless, BASIC will clobber our defenceless little routine the 
first chance it gets, because it’s always moving things around in memory in ways that 
aren’t always easy to predict. One way out of this problem is to fool BASIC into thinking 
that the top of memory is below where it really is, and use the resulting "attic” for any 
programs we want preserved. To do this, we POKE the bytes 16388 and 16389 (which 
together form a system variable called RAMTOP) with the address from which we wish 
to start our program. In other words, this is the first address which is unavailable to 
BASIC. As usual, the low byte contains the least significant value. So. taking an example 
for a IK machine. RAMTOP contains the hex value 4400 to start with. If we want to 
allocate a 256 (decimal) byte attic, we have to set RAMTOP to 4300 so: 

POKE 16388,0 [=00 hex] 

POKE 16389.67 [= 43 hex] 

(Incidentally, 4300 hex = 17152 decimal, and you can omit the POKE 16388 unless, 
for some reason, you’ve changed it from its usual 0 value previously.) 
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Now we type NEW because BASIC only notices that RAMTOP has changed when 
NEW is executed. Next, load the “loader” program and run it. In response to its BASE 
ADDRESS request, type 17152, and, to NO. OF DATA BYTES, type 1. Finally, key in 
the machine code (62, 4, 6, 7 etc.) terminating with a negative value, a delimiter (see 
Timex/Sinclair 1000, p. 39) ignored on loading but signalling “end of code listing”. 

The system responds by printing the contents of bytes from 17152 onwards. In 17152 is 
11, which is the sum of 4 and 7, and this shouldn’t surprise us much, since that’s where we 
asked to store the result, and it’s also the byte we allocated for data. The rest of the 
“memory dump” just confirms that the program is correctly stored. 

Experiment, by altering the values being added. (Just POKE new values into 17154 
and 17156 and GOTO 220). Or put the result somewhere else—17153, say. See how it 
changes the program? 

In particular, ti^ adding 240 to 100 (decimal). The result isn’t 340! Why? 

Think about it in binary: 


240 1 1 1 1 0 0 0 0 

100 + 0 1 1 0 0 1 0 0 


0 10 10 10 0 = 84 


1 

The sum generates a 1 in the ninth bit, which can’t be held in an 8-bit byte, so it falls off 
the end and the quoted result is too small by the value of that ninth bit—256. No check 
has been made, no helpful error message printed. When you write machine code you’re 
on your own. What you don’t test for, you don’t find out about. 


AN IMPROVED LOADER 

For that first try, I gave you a program that loaded decimal opcodes. That was so you 
could concentrate on the mechanics without worrying about hex codes. But hex is so 
much more convenient. Here's how to modify LOADER to accept hex, by combining it 
with the decimal/hex converter in Chapter 11. 

Change lines 120, 130. 140,150 to: 

120 INPUT C$ 

130 IFC$ = ‘S ' THEN GOTO 180 
140 PRINT C$ 

150 POKE A. 16 * (CODE C$ (1) - 28) + CODE C$ (2) - 28 

The procedure is exactly as before; but now at each input you key in the hex code: 3E, 
then 04, then 06, etc. Don't omit the zeros. Use "S" to end the inputs, in place of the 
previous “negative number" delimiter. 

In the above description, I assumed you might only have IK of memory. Machine code 
is of course a useful space-saver with IK; but anyone interested in it is likely to have 16K. 
Further, some of our later routines using the display file need at least 4K. To reserve a 
256-byte attic in 16K, proceed as follows. 


POKE 16389. 127 
NEW 
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Now load in the machine code. Replace 4300 hex by 7F00 hex; and 17152 decimal by 
32512 decimal. Appendix 2 contains a table for allocating memory in 256-byte blocks in 
16K. 

From now on, Fm only going to give the hex codes. You can either modify LOADER 
as above, or you can convert from hex to decimal using Appendix 1. Since the latter is 
tedious, and it’s easy to make errors, I strongly recommend the former. 

A really versatile loader is given in Appendix 6: HELP A. 


A USEFUL TRICK 

It’s a terrible nuisance that the 1000 needs a NEW before it recognizes changes to 
RAMTOP. You’re half way through typing in a BASIC program, with some machine 
code to accompany it later . .. Bother! You’ve forgotten to allocate memory. 

Using what I’ve told you so far, all you can do is SAVE on tape; reset RAMTOP, then 
LOAD back in, and continue. But there is a way to avoid this, by using a ROM routine. 
(As I say elsewhere, I don’t think that learning a list of ROM routine addresses to call is 
really the way to get into machine code; but this is so useful. I’ll make an exception.) 

Suppose you want to allocate a 256-byte attic, leaving your precious BASIC intact. 
From the keyboard, type 

POKE 16389,127 [reserve space] 

PRINT USR 1040 [call from ROM] 

You’ll get a listing and the program will halt. Restart with RUN (this technique loses 
your variables anyway). That’s it. For different sizes of attic, change the 127 (and POKE 
16388 with the junior byte if this isn’t zero). 

You can use this in a program, but the program will halt after the USR 1040, and need 
a manual restart. And directly entered variables will be lost. 

You can store machine code other places than above RAMTOP; see Chapter 22. But 
all methods have their quirks. 
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There are 694 Z80 instructions: here’s a selection of the more 
fundamental and accessible ones, and what they will do. 


19 A Subset of Z80 instructions 


Tm not going to describe every one of the 694 opcodes the Z80 has; that would be tedious 
and unnecessary. (But see Appendix 4.) We’ll look at a subset of 30-odd types of 
instruction (covering about 230 actual commands). Unfortunately, not all of them can 
use all the addressing modes. Here’s a quick reference table showing which instructions 
can use what; the opcodes are given in Appendix 5. 


\ ^ 

\ ^ 

\ ® 
AddressX d 
Mode \e 

LD 

ADDADC 

SUB SBC 

AND 

OR 

XOR 

CP 

INC 

DEC 

SLA 

SRA 

SRL 

JR 

JRC 

JRNC 

JRZ 

JRNZ 

DJNZ 

JP 

JPZ 

JPNZ 

JPC 

JPNC 

JPP 

JPM 

LD 

ADD 

ADC 

SBC 

INC 

DEC 

PUSH 

POP 

Register 

LDr.s 

ADDA.r 

INCr 





ADDHL.r 

IN( r 

Immediate 

LDr.n 

ADD A. n 



JPnn 

JPZnn 

LD r. nn 



Direct 

LDA. (nn) 

LD (nn). A 






LDHL.(nn) 

LD(nn).HL 



Indirect 

LDA. (HL) 

LD (HL). A 

ADDA. (HL) 

INC(HL) 


JP(HL) 





Indexed 

LDA.dY + d) 

LD(IY + d).A 

ADDA. (lY + d) 

INC (lY + d) 

JRd 







8-bit operations 16-bit operations 


The notation in the table needs some explanation. Some of the opcodes will be un¬ 
familiar, but we’ll deal with those later. Otherwise, the conventions are: 

1. Each entry in the table shows an example of the format of the instruction type. 
Any of the other opcodes in that column could be substituted. 

2. “r” or “s” denotes any register. Whether this is an 8-bit or a 16-bit register 
depends on which part of the table the instruction is in. For instance, in the LD r, s 
instruction, r and s are any 8-bit registers (A, B, C, D, E, H or L), but in ADD 
HL, r “r” is one of BC, DE, HL, SP. 

3. “n” is any 8-bit number, “nn” is any 16-bit number. 

4. If a register is explicitly stated, as in LD A, (nn), then this is the only register which 
may be used for this purpose. 

This is a wild oversimplification. Sometimes, other registers are usable, but the 
point is that the set of instructions I’ve shown are always OK and you can worry 
about extending your vocabulary of instructions when you’re handling this lot 
confidently. 
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5. “d” is any 8-bit number, but it’s always added to some 16-bit value. In other 

words, it’s an indexing displacement. 

Now let’s look at the new opcodes: 


AND 

This operation takes the contents of the A-register, and another 8-bit field, and 
examines these, bit by bit. Only if corresponding bits are both “1” does it put a “1” back 
in this position in the A-register. Otherwise it inserts a “0”. 

For instance, AND A, has the following effect: 

A-register before the operation: 00110101 

07: 0 0 0 0 0 1 1 1 

A-register after the AND: 00000101 

See how the junior three bits have been transmitted? So you can use AND to select a 
portion of a byte. 


OR 

This works in a similar way to AND, but this time, the resulting bit is a “1” if either of the 
initial bits is a “1”. So OR A, 05 gives: 

A-register before: 01001011 

05: 0 0 0 0 0 1 0 1 

A-register after: 01001111 

Now, certain bits are being forced to “1” regardless of their original value. 


XOR 

Here the initial bit values must be different for the result to be a “1”. XOR A, B3 gives: 

A-register before: 01011010 

B3: 10 110 0 11 

A-register after: 11101001 

It’s particularly useful for flipping a register from 0 to 1 and back again. If the A-register 
contains 0 to start with, every time the instruction XOR A, 01 is executed, the value in 
the A-register will flip. (0 to 1, back to 0, back to 1 and so on.) 


CP 

This is the “Compare” instruction. The contents of the A-register are compared with 
those of another 8-bit field. That raises a problem, though: how is the result of the 
comparison signalled? 

This is what the F ( or flags) register is used for. Each bit of the F-register holds some 
information about the effect of the last instruction to alter them. (Not all instructions do 
alter them). 

The flags which most interest us are the Carry, Zero, Overflow and Sign flags. CP can 
alter any of these, but the one of most significance here is the Zero flag, which is set if the 
two values being compared are equal. 
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If the A-register contents are less than those of the compared byte, the sign flag is set. 
This is equivalent to saying “the result is negative”. This is all you need to know about 
the flags at the moment: it’s an intricate topic if you delve deeper. 


THE JUMPS 

All the conditional jumps branch (or not) depending on the contents of the flags. So, for 
instance, JPZ says “jump if the Zero flag is set”. Now we can see how the CP instruction 
can be used. Suppose, for example, that we wish to see if a particular byte, pointed at by 
HL, contains IE hex. If it does, we want to branch to 447B. The code is: 

LD A, IE 3E IE 

CPA,(HL) BE 

JPZ447B CA7B44 

All the other jumps behave similarly; JPNZ says “jump on a non-zero result” (zero 
flag not set), JPP says “jump on a positive result” (sign flag not set), JPM says “jump on a 
minus result” (sign flag set), JPNC says “jump on no carry” (carry flag not set), and so 
on. All of them have one thing in common, and that is that the address of the jump is 
fixed. In other words, if, for any reason, we would like a routine to run somewhere in 
memory other than where we first loaded it, all the jump addresses must be changed. 
The Z^ deals with this neatly by allowing “relative jumps” (JR). In other words, you 
can jump so many bytes forward (or back) from where you are. This displacement is held 
(in 2’s complement notation. Appendix 1) in 1 byte, so the distance which can be jumped 
can’t exceed 128 bytes backwards or 127 bytes forwards. 

The displacement is calculated from what the PC value would have gone to next, had 
no jump occurred; namely, the address of the next command in the program. Like this: 


JR command 


■> 


displacement code-> 


where PC would have gone 



size of 

displacement 
to be coded 
as “?” 


80 


FD 

FE 

FT 

00 

01 

02 

03 


7F 

t 

2’s 

complement 
hex code 
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Here’s an example. We want to examine each byte of memory in turn for the first 
occurrence of IE hex. Assume for simplicity that the start address is already in HL. We 
could write: 


LD A, IE 

LOOP: CPA,(HL) 

INC HL 
JRNZLOOP 

Two points need explaining. First, I’ve sneaked in a new instruction: INC. This is short 
for INCrement. It just adds 1 to the contents of the specified register; so the compare 
operation is always looking at the next memory byte because HL is being bumped up by 1 
every loop. (By the way, DEC, short for DECrement, does exactly the opposite.) The 
second point is that there’s no obvious difference between JRNZ LOOP and JPNZ 
LOOP. It isn’t until we assemble the instructions into machine code that the difference is 
clear. Suppose the code is to be loaded from 4300 hex: 


Address 

Instruction 

Hex code 

4300 

LD A, IE 

3E IE 

4302 

LOOP: CPA,(HL) 

BE 

4303 

INC HL 

23 

4304 

JRNZ LOOP 

20 FC 


Why is FC in the address part of the JRNZ instruction? It works like this: when the 
JRNZ instruction is executed the PC is bumped up by 2 because it’s a 2-byte instruction. 
So the PC is now at 4306. We want to jump to LOOP, which is at 4302, 4 bytes back, or 
-4 bytes away, to use the ZSO’s way of thinking about it. Now, 4 in binary is 00000100 
and we create -4 by flipping the bits and adding 1 (2’s complement, remember?). So: 


0 

0 

0 

0 0 

1 

0 

0 









flip the bits 

1 

1 

1 

1 1 

0 

1 

1 







+ 

1 

add 1 

1 

1 

1 

1 

111 

1 

0 

0 





1 

1 




convert to hex 


F 


C 


Another thing which may be worrying you: INC HL doesn't alter the flags, so I'm safe to 
test after the increment. 

The same program with absolute jumps would have looked like: 
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Address 

Instruction 

Hex code 

4300 

LD A, IE 

3E IE 

4302 

LOOP: CP A, (HL) 

BE 

4303 

INC HL 

23 

4304 

JPNZ LOOP 

C2 02 43 


Notice that the JPNZ instruction has 3 bytes because it contains a whole 16-bit address; 
and don’t forget about swapping the 2 bytes of that address around! 

There’s one very powerful instruction in the Jump group I haven’t mentioned yet— 
DJNZ. It decrements the B-register by 1 and jumps (relative) only if the result is 
non-zero. 

Suppose our little “search for IE” program is only to search a region one hundred (hex 
64) bytes long, after which it should leave the loop whether it’s found a IE or not: 


LDB,64 
LD A, IE 

LOOP: CPA,(HL) 

JPZ GOTCHA 
INC HL 
DJNZ LOOP 


0640 

3E1E 

BE 


CA-(address for GOTCHA) 

23 

10 F9 


The loop is executed one hundred times, unless a IE is found, in which case a branch to 
GOTCHA occurs. In other words, DJNZ acts like a simple FOR loop in BASIC. 

Note that with all the relative jump commands JR, JRC, JRNC, JRNZ, and JRZ, the 
size of jump is calculated the same way. A table of 2’s complement hex codes is given in 
Appendix 1 for hand-coding of jumps; our utility routine HELP A in Appendix 6 will 
work out relative jumps automatically for you, during the writing of the code. 


ADC and SBC 

These are the “ADD with Carry” and “SUB with Carry” instructions. I said earlier that 
there is a Carry flag in the flags register. This gets set if there is a carry generated out of a 
register by an arithmetic instruction. The ADC instruction will act just like ADD, except 
that it will add 1 more in if the Carry bit has been set by a previous operation. The SBC 
instruction works the same way, except that it will subtract the Carry flag. 


THE SHIFTS 

The shift instructions, SLA, SRA and SRL, all have the effect of shifting bit-patterns 
around. 

SLA shifts the pattern left by 1 bit, so if the B register contains: 

0 0 10 1 10 0 

and SLA B is executed, the result is: 


01011000 


(Notice that a zero is used to fill on the right.) 

Since 00101100 = 44 and 01011000 = 88 (decimal) you can see that the effect is to 
multiply by 2. 
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Another SLA B will give: 


10110000 

Since the senior bit is now 1, this will be seen as a negative number, and the Sign flag will 
be set. So far as the programmer is concerned, what’s happened is that the value (176) 
can’t be held in a byte, so we’ve got an overflow condition. 

Right shifts work much the same way, but there’s one important thing to note: SRL 
fills the senior bit with a zero, but SRA fills with whatever was there before. 

For instance: 



The reason is this: SRL is a shift right logical^ which simply shifts the bit pattern without 
altering it. SRA is a shift right arithmetic, which treats the operation as “divide by 2”. 
Now, when a negative number is divided by 2 the result should still be negative, so we 
have to preserve the sign bit. 



PUSH and POP 

You’ll probably remember these terms from our discussion on stacks. They’re used here 
in exactly the same way, and allow us to access the machine stack other than through a 
subroutine call. 

This can be useful for saving values temporarily. For instance, suppose you’ve got a 
value in BC which you want later, but just now you’d like to use BC for something else. 
You can write: 

PUSH BC 


Code 

using 

BC 


POPBC 





This is often done before a subroutine CALL as well, so that it doesn’t matter what 
registers the subroutine uses: it can’t interfere with the calling program’s data. You may 
see code like: 


PUSHBC “ 
PUSH DE 
PUSHHL _ 
CALL4FA1 
POPHL ~ 
POP DE 
POP BC _ 


save the registers 


restore register values 
(note the order!) 


assuming that the A-register is manipulated by the routine, so we don’t need to save it. 


Warning 


Unless you deliberately choose to alter it, the stack pointer SP will be set according to the 
operating system of the ZX81. There’s no harm in leaving it at that value, provided you 
make sure that PUSHes and POPs cancel out in pairs, so that SP returns to its initial 
value on leaving the machine code routine. Similarly CALLs and RETs have to match. 
(USR generates a CALL, matched by the final RET that is tacked on to the end by the 
LOADER routine.) 


A16.BITQUIRK 

One feature of the 16-bit operations (PUSH, POP, LD in particular) which is important 
to grasp is the order in which bytes are transferred from register to memory and vice 
versa. It’s like this: 

LD (4105), HL 

will have the following effect, if HL contains 1E4F: 


H 



4105 

4106 


‘junior 

specified address; and the most significant or 
following this. Conversely, 

LD HL, (4105) 


byte in the register is loaded into the 
“senior” byte is loaded into the byte 


would have exactly the reverse effect. (NB: it codes as 2A 05 41, following the standard 
convention!) Similarly 

LD HL 1000 


(an attempt to load HL with the value 1000 hex) encodes as 

210010 


so that, even though 1000 is data, not an address, its bytes get transposed as usual. 
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CRASHES 


When a BASIC program crashes, there’s little harm done: you can always break out, one 
way or another, without losing the program. But machine code crashes are more 
spectacular, and infuriating. Spectacular, because they often signal their presence by 
drawing op-art patterns all over the screen; and infuriating because (on the 1000) the 
only way to break out of them is to pull the power plug out and lose the contents of 
RAM. You want to see a crash, to check this? OK, try this little program: 


1 REMX 

2 POKE 16514,118 

3 RAND USR 16514 



A Machine Code crash. Start again! The variety of “crash" displays will amaze you. . . 


The screen blanks, and the machine no longer responds to the keyboard. This is because 
it uses a ROM routine to scan the keyboard, but the BASIC operating system isn’t in use 
during a USR call of a machine code program. Once a crash occurs, you’re stuck with it: 
pull the plug and start again. (However, there’s no way to alter the ROM contents, so 
don’t worry about doing any lasting harm! It is you, not the 1000, that will suffer!) But 
there are some simple precautions worth taking. 

1. Check all machine code listings scrupulously and make sure you have input them 
correctly. 

2. Afewer use HALT (hex code 76). 

3. Make sure that CALLs and RETs match, as do PUSHes and POPs. 

4. Make sure you call the correct starting address. 

5. Unless there’s not much to lose, SAVE what you can on tape before calling USR. 
(Our utility programs HELPA and DOWNLOAD permit this in useful ways.) 
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Machine code has no instruction for multiplying numbers; 
but you can do it if you combine arithmetic, logic, and shifts. 
Digging deeper now . .. 


20 A Machine Code Multiplier 


Now let’s write a few simple routines. Remember I said that there’s no Z80 multiply 
instruction? Let’s write a subroutine to do the job. 


AN EXAMPLE 

First we should examine the nature of the problem, and there’s no better way of doing 
that than looking at an example. We’ll keep things as simple as possible, and work in 
8-bit registers; so if we want to multiply 9 by 13 it will look like: 


X 00001101 

Now we can treat this as a conventional long multiplication, but because it’s in binary, it’s 
actually easier than usual; if the current digit we’re multiplying by is 1, copy the top line; 
if it’s zero, do nothing: 

00001001 P 

X 00001101 Q 

00001001 

00100100 

01001000 

0 1110 10 1 

Of course we’ve had to add in zeros on the right at each stage, just as we would in a 
decimal long multiplication. In machine code terms, that’s equivalent to a shift left. I’ve 
called the two numbers P and Q, for reference. 

While P is shifted left, it’s also going to be convenient to shift Q right, because that way 
we only need to keep examining the junior bit of Q to determine whether to add P into 
the sum or not. 
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PROCEDURE 


Assume that P and Q are in the D and E registers 

1. Set the A-register to zero. 

2. If the junior bit of E is 1 then add D into A 

3. Shift D left. 

4. Shift E right. 

Here’s a first stab at the code: 

LDA, 00 

LDB, dS 

The first step s obvious; the second sets B to act as a loop counter in conjunction with a 
DJNZ to come at the end. Now we want to test the junior bit of E. The only way we 
currently have of doing that is to use a mask pattern ((NHWWWl) with an AND operation 
so let’s set up the C register to that pattern: 

LDC, 01 [see below for hex coding] 

We can only AND with the A-register, which will destroy its current contents, so we’ll 
save it in L first: 

LOOP: LD L. A 

then extract the junior bit of E, and restore the A-register: 

LDA.C 
AND A. E 
LDA.L 

If the result of the AND was zero, we need to jump round the “add D into A” part of step 
2 so: r F 

JRZ SHIFT 

(Note that since LD doesn’t affect the flags, the JRZ still refers to the AND.) Otherwise 
perform the ADD: 

ADD A, D 

Now do the shifts: 

SHIFT: SLA D 
SRAE 

and see if we’ve done the loop enough times yet: 

DJNZ LOOP 
RET 


. The procedure is: 




repeat these 
^ steps 8 times 
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THE CODE 

Here’s the whole thing: 


Address 


Instruction 

Hex code 

mb 


LD A,00 

3E00 

mi 


LDB,08 

0608 

vm 


LD C. 01 

0E01 

0006 

LOOP: 

LDL, A 

6F 

0007 


LD A,C 

79 

0008 


AND A, E 

A3 

0009 


LD A,L 

7D 

000A 


JRZ SHIFT 

2801 

000C 


ADD A, D 

82 

000D 

SHIFT: 

SLAD 

CB 22 

000F 


SRAE 

CB 2B 

0011 


DJNZ LOOP 

10 F3 

0013 


RET 

C9 


If you want to try this program out, you’ll have to arrange for the D and E registers to 
hold the values to be multiplied. So you could precede the program by something like: 


LD HL, 4300 

21 0043 

LD D, (HL) 

56 

INC HL 

23 

LDE,(HL) 

5E 


and then POKE 4300 (hex) and 4301 (hex) with the values to be multiplied, before 
calling the program. These .two bytes will, of course, be the two zero bytes at the 
beginning of the routine, so the LD HL, 4300 will start in 4302. Note that I didn’t assign 
actual addresses to the program, but simply started at zero. This is because all the jumps 
are relative, so actual addresses are unimportant; only displacements matter. For 
example, with 16K you can replace all 43s in the above by 7Fs, to work with a 256-byte 
attic. 



143 



You’ll also need to output answer: at the moment it’s just sitting in the A-register. 
A simple way to do this is to stick the answer into the display file (see next chapter for 
details) by adding the following code at the end, in place o/the C9 (RET) instruction, 
which is there only because I said this was going to be a 5 M 6 routine. 


0013 

LD HL (D-FILE) 

2A0C40 

0016 

INC HL 

23 

0017 

LD (HL) A 

77 


Add this at the end; add the bytes 07 and 08 at the front (or POKE them later); enter 
using LOADER with 2 data bytes. The letter “S” will appear at the top corner of the 
screen. The code for S is 56; and that’s the product of the two numbers 07 and 08 you 
POKEd in. Of course a more elegant display routine would be nice: think about PRINT 
USR or read the next chapter and design one. But for a test, this method suffices. 


BIT 


Now, I have a confession to make; there’s an easier way of testing to see if the junior bit 
of E contains 1. There’s an instruction BIT 0, E which does the job. So: 


LOOP: LD L, A 

6 F 

LD A,C 

79 

AND A, E 

A3 

becomes just: 



LOOP: BIT0,E CB43 


and the LD A, L has to disappear as well. 

Why didn’t I tell you that in the first place? Well, firstly, I promised to use only the 
subset of instructions in the table, a promise I’ve now broken. But I’ve made an 
impoitant point in the process—that it’s possible to do things satisfactorily without 
knowing the full instruction set. 

This has been something of an academic example; I chose it because it uses several 
common instructions in conventional, but not necessarily obvious, ways, but I’m not 
suggesting that you will find a need for dozens of 8 -bit integer multiplications. 
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To control graphics from machine code, you must know where the 
display is stored, and how to alter it. Change the whole screen to 
inverse video, or draw a line of characters, all in a flash! 


21 The Display File 


21 The display file 

So now for something more clearly useful. Fed up with BASIC’s ability to draw graphics 
lines at a snail’s pace? Let’s see if we can write a machine code subroutine which will draw 
straight lines from any point on the screen running horizontally, vertically, or diagonally. 

At least, that’s the target. Let’s deal with the problem in easy stages. Obviously, we 
need to know something about how the 1000 handles displays before we can get 
anything on the screen. As you’ve probably seen from the Manual, there’s an area of 
memory called the display file from which the screen display is generated. All we have to 
do is store character values in this region to get them displayed. 

The position of the display file isn’t fixed. (It depends on the program size.) There is, 
though, a pointer to its first byte, called D-FILE, and D-FILE has the hex address 4WC, 
decimal 16396. So the display file starts at PEEK 163% + 256 * PEEK 16397. 

The size of the display file isn’t fixed either. (At least, it isn’t on IK systems, and 
although it normally is on 16K systems, this isn’t guaranteed; so it’s safer not to make use 
of any feature based on such an assumption if you can avoid it.) The display file begins 
with a newline character, and ends every line with one as well. So, for instance, the state 
of the display file after the following statements: 

10 CLS 

20 PRINT “ABC ” 

30 PRINT “□□□DEF” 
would be: 


in IK, or in 16K if RAMTOP has been lowered to under 3V4K. With more than that size 
of memory, it will be padded out with the “missing” blank spaces. (I’m using “<” to 
represent NEWLINE and to represent SPACE.) 

This is a neat way of saving precious memory when only a small part of the screen is 
being used, but it doesn’t make our problem any easier. 





DISPLAYING A CHARACTER 


Anyway let’s try something simple, like putting a graphics symbol at the top left-hand 
comer of the screen. If the screen is blank to start with, there will just be 25 newlines in 
the display file. So our problem is to overwrite the second of them (where the “A” is in 
the above example) with our chosen symbol. 

First, we load HL with a pointer to the display file. This is called D-FILE and is at 4(J0C 
hex: 

LDHL,(4(WC) 2A0C40 

Now bump HL to point one character further along: 

INCHL 23 

Now put the graphics character (88 hex, say) in the A-register: 

LD A, 88 3E 88 

and, finally, put this value where HL is pointing: 

LD (HL), A 77 

This works OK, but we should think carefully before extending the idea. After all, we’ve 
just overwritten one of the newlines, which is doubtless being used by one of the ZX8rs 
system routines to handle the display. Sooner or later we’ll confuse that routine if there 
aren t enough newlines left for it to play with. Of course, if we’re overwriting a character 
that is already in the display, this problem doesn’t arise. So, for instance, we could 
change the A, B or C of the first example without affecting the newlines at all. One way 
out of the problem, then, is to fill the portion of the screen we’re interested in with 
spaces. On a 16K machine with RAMTOP above 3y4K, CLS does this, creating 24 lines 
of 32 spaces each. On a IK machine we could write: 


10 

FORL=1T05 

20 

FORC= 1T032 

30 

PRINT 

40 

NEXTC 

50 

PRINT 

60 

NEXTL 


to set up the top 5 lines to spaces. 


VIDEO-INVERSION 


Now for something more ambitious. 

Bored with the same old display all the time? How about white-on-black? We’ll write a 
routine to invert the display file. The principle is simple: mn through it changing each 
character to its inverse, except for NEWLINEs. For comparison, here it is in BASIC. 


10 LET D = PEEK 163% + 256 * PEEK 16397 

20 LETB = 22 

30 LETD = 0-1-1 

40 LET P = PEEK D 

50 IFP= 118 THEN GOTO 100 

60 POKE D, P -t-128 - 256 * (P > 127) 

70 GOTO 30 
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100 LETB = B-1 
110 IFB = 0THENSTOP 
120 GOTO 30 



Video-inversion of the display file. 

Type this in, set up a nice display, and run the beast. Yes, well, it’s a bit slow, isn’t it? A 
machine code version ought to be faster. The machine code follows a very similar pattern 
to the BASIC program: 


dm 


LD B, no.-of-lines 

0616 

dm 


LD HL, (D-HLE) 

2A0C40 

dm 

LOOP: 

INC HL 

23 

dm 


LD A, (HL) 

7E 

dm 


CP A, newline 

FE76 

dm 


JRZ, SKIP 

28^ 

mB 


ADDA, 128 dec 

C680 

000D 


LD (HL), A 

77 

mE 


JR, LOOP 

18 F5 

mid 

SKIP: 

D JNZ LOOP 

10 F3 

mil 

(tack on standard ending via LOADER) 



The addresses are relative ones: load this up as usual with the LOADER. The relative 
jump sizes (underlined) have to be calculated separately at the end, using the table in 
Appendix 1. 

Now set up a BASIC routine to print out a nice display, and call the above machine 
code via USR. Now it’s very fast indeed! Note how the machine code mnemonics parallel 
the BASIC. And, a bonus in machine code: to invert video, add 128 (hex 80) to the code 
and don’t worry about going over 256, because the extra carry digit just drops off the end 
of the register. (NB: with IK, not all of the display gets inverted. Why not? Which bit 
does?) 
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LINE-DRAWING 


To get a horizontal line, 10 characters long, on the top line of the display we could 
execute the following code: 


LOOP: 


LDA,88 

3E88 

LD B, 0A 

060A 

LD HL. (40(JC) 

2A0C40 

INCHL 

23 

LD (HL), A 

77 

INCHL 

23 

DJNZ LOOP 

10 FC 


set value to be displayed 
set loop count 

point to first character in display file 
display 

point to next character 
do it again 


To do the same job anywhere else on the display, all we need to do is alter the value in 
HL to start with by an appropriate offset. In principle if s easy to calculate the necessary 
offset. Let’s think about the display file like this: 


Column 
Row 0 

i 1 
2 

3 

4 


1 2 3 

01234567890123456789012345678901 

>□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□> 

□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□> 

□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□> 

□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□> 

□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□> 


and so on 


If the HL is incremented after having been loaded from D-FILE so that it i 3 oints at 
column 0, row 0, then we simply multiply the row number we want by 33 and add on the 
column number. That is: 

offset = row * 33 + column 

Provided the row value never exceeds 7, we could use our 8-bit multiplier here. But 
there’s a neater way: 

offset = row * (32 + 1) + column 
= row * 32 + row -I- column 
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Despite the fact that this expression for the offset seems more complicated than the 
original, it has the advantage that the multiplication is now by a power of 2 (2*), so all we 
have to do is shift row left 5 times to evaluate row * 32. 





Now let’s imagine that the row value is available in the E-register, and the column 
value is in the C-register. We can calculate the offset like this: 

LDB,05 0605 

SHIFT: SLA E CB 23 

DJNZ SHIFT 10 FC 

Hold on, it’s not quite as easy as that! This piece of code shifts the E register contents left 
5 times all right, and that’s fine if row * 32 is less than 255, but it could easily be more than 
that, and the E-register will overflow. So we need a 16-bit register. If we use DE, the 
above code can be used as a basis for the routine, but there are some pieces to add on. 
First, we’ll have to make sure that D contains zero to begin with. Second, as bits shift left 
off the end of E we want them to appear in D and then shift along D. This will work: 



LDD,00 

16 W 

clear D 


LDB,05 

0605 

load loop count into B 

SHIFT: 

SLAD 

SLAE 

CB22“|_ 

CB23_|~ 

shift left DE 


JRNC EOL 

3001 

go to End of loop on no carry 


INCD 

14 

put the carry into the junior bit of D 

EOL: 

DJNZ SHIFT 

10 F7 

test for end of loop 

Now we want to add this into HL, having first 
character in the display file: 

loaded it with the address of the first 


LD HL, (400C) 

2A0C40 



INC HL 

23 



ADD HL, DE 

19 



Unfortunately, what we now need to do is to add the row value into HL, and the copy in 
E has been destroyed by the shift operations. That’s no real problem, because we 
presumably passed the row value from BASIC by POKEing it to a byte just before the 
beginning of the machine code routine in the usual way, and it’s still available there. So 
all we have to do is zero D, load E from this byte and ADD HL, DE again. But this does 
prompt the question, “Was there a neater order in which to do things?’’ 

Well, there was: 


LD HL, (400C) 

2A0C40” 

compute address of first character 

INC HL 

23 

in display file 

LDD,00 

1600 

— add row value to it 

ADD HL, DE 

19 J 


LDB,05 

0605 


as before 


compute 32 * row 

DJNZ SHIFT 

10 — 


ADD HL, DE 

19 

add this into HL 

ADD HL, BC 

09 

add column value into HL 
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Now we simply execute the “draw a line” routine as before: 


LD A, 88 3E 88 

LDB,0A 06 0A 

LQOP: LD (HL), A 77 

INCHL 23 

DJNZLOOP 10 FC 


(or whatever) 


The hex codes are given below, tidied up. 

There’s no test in the routine to check that the line being drawn doesn’t go over the 
right-hand edge of the display, and of course, such a check should be included. Other¬ 
wise a pile of end-of-line returns could get clobbered. The easiest way of doing this would 
be to test whether the character we’re about to overwrite is a newline. If so, don’t. 

This routine produces a horizontal line because of the INC HL instruction in the loop. 
Change HL by some value other than 1, and we get different shapes. INC HL twice, and 
eveiy other print position will display the character, for instance. Add 33 (decimal) into 
HL in every loop and we get a vertical line. Add 34 (decimal) into HL in each loop and 
we get a diagonal line. 

You could have a library of such routines and simply call one whenever you want that 
kind of line. 


LISTING 

Here’s the complete code. This time we won’t bother with addresses in the listing: 
they’re not important (thanks, once again, to relative jumps). 



LDC,00 

mm 


LDE,W 

lEW 


LD HL, (400C) 

2A0C40 


INC HL 

23 


LD D, 00 

16 W 


ADD HL, DE 

19 


LDB,05 

0605 

SHIFT: 

SLAD 

CB22 


SLAE 

CB23 


JRNC EOL 

3001 


INCD 

14 

EOL: 

DJNZ SHIFT 

10 F7 


ADD HL, DE 

19 


ADD HL, BC 

09 


LDB,W 

%m 


LDA,W 

3EW 

LOOP: 

LD (HL), A 

77 


LD DE,WW 

nmm 


ADD HL, DE 

19 


DJNZ LOOP 

10 F9 
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The zero bytes underlined must be poked before calling the routine, as follows: 


Start address +1: 
Start address -I- 3: 
Start address + 25: 
Start address + 27: 
Start address -l- 30: 

Start address -1-31: 


starting column (e.g. 05 for column 5) 

starting row (e.g. 07 for row 7) 

number of characters to be plotted (e.g. 0A) 

code of graphics character (e.g. 86 for HJ ) 

value added to HL between plots (e.g. 01 for a horizontal line, 

21 for a vertical line, 20 or 22 for diagonal lines) 

not normally used unless the value to be added exceeds 255, 

otherwise set to 00 


Once you’ve loaded this up. and seen what it does, think about incorporating it into 
A51C programs to generate, say, a series of squares (such as the RECTANGLE PLOT 
on page 41 of T^/S^Mr 1000). Use RND to find the top left-hand comer (column 
and row) and the length of side. Then POKE the relevant addresses in the machine code 
routine, and call it via USR. Do this four times for the four sides of the (open) rectangle 

Don t forget to test the sizes to see if it will all fit on the screen! 
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Some new, powerful commands: block search and block transfer. 
The alternate registers. And programs to SCROLL limited 
sections of the screen, or scroll sideways, at high speed. 


22 Some Things I haven’t told you 


First things first: actually, it was Humpty-Dumpty (see page 115). 

I’ve deliberately simplified (even oversimplified) in places in this chapter, and 1 don’t 
apologize for that. After all, machine code isn’t the easiest thing to tackle, and listing all 
its features all at once is just confusing. On the other hand, if you’ve looked at other 
books on Z80 machine code, or 1000 machine code listings in magazines, you may well 
be wondering why I’ve frequently done things in an apparently cack-handed way. 

So I’ll try to redress the balance now. 


BLOCK SEARCH 

First, there are some very powerful instructions which will search a whole block of 
memory. I’ll take CPDR which is short for “compare, decrement and repeat’’ as an 
example. 

If I write a piece of code like this: 


LD BC, 0100 

010001 

LDHL,5000 

210050 

LDA,05 

3E05 

CPDR 

EDB9 


NEXT:- 

what happens is this: 

When the CPDR instruction is encountered the value in the A-register is compared 
with the contents of the byte HL is pointing at. If they are equal, control passes to 
NEXT: If not, BC and HL are both decremented by 1, and the “compare” is repeated 
until a match is found or until BC contains zero. In other words, those 4 instructions say: 
“Find the first occurrence of a byte containing 05 from address 5000 (hex) down to 
address 4P00 and leave HL pointing to it. If there isn’t one, zero BC.” 

So the first example I gave of using jumps, which was a little “compare” loop, could 
have been done much more easily. But, of course, it wouldn’t have illustrated jumps! 

BLOCK TRANSFER AND PARTIAL SCROLLING 

Secondly there are also some block transfer commands LDIR and LDDR which are 
invaluable for shifting blocks of data around in memory. For instance, to use LDIR, you: 

• Load HL with the address of the first byte to be transferred. 

• Load DE with the address of the first destination byte. 

• Load BC with the number of bytes to be moved. 
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Partial scrolling. 

Then LDIR transfers the first byte; increments HL and DE; decrements BC, and keeps 
doing this until BC hits 0. LDDR is similar, but it decrements HL and DE (and 
decrements BC as before). To see LDIR in action, here’s a very useful routine that lets 
you SCROLL a band of columns on the screen, leaving the rest fixed. 


COLUMN 
WIDTH 
LDA,00 
LD HL, (D-HLE) 
LD DE, (COLUMN) 
ADDHL,DE 
INCHL 
LOOP: LD D, H 
LDE,L 
LD BC, 0021 
ADD HL, BC 
PUSH HL 
LD BC, (WIDTH) 
LDIR 
POPHL 
INCA 
CPA, 16 
JRNZ, LOOP 


0700 

1 set up 

WW ^ 

1 data 

3E00 


2A0C40 

get ready 

ED 5B 007F 

— for block 

19 

transfer 

23 


54 

5D 

012100 

09 

E5 

ED4B 027F 

EDB0 

shift section 

of a line up 

to line 

above 

El 

test and 

3C 

^ repeat until 

FE16 

last line 

20 ED 

reached 


The numbers in COLUMN and WIDTH can be POKEd to change them: here I’ve set up 
a scroll starting in column 7 and of width 9, which means that columns 7,8,9,10,11,12, 

13,14,15 will SCROLL and the rest not. There are 4 data bytes before the start address. 

To see this in action, you’ll need to give it something to scroll: a clear screen isn’t too 
dramatic! One way to do this is to add some lines to LOADER: 


212 F0RI = 1T07 

214 PRINT “AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC’; 

216 NEXT I 

And, for scrolling up more than one line, put the USR instruction inside a loop: 

218 F0RI=1T013 
220 LETY = USR(B + D) 

222 NEXT I 

Experiment, putting different designs on the screen before scrolling. 

The underlined 16 can be changed (but only to something smaller) to scroll only down 
to a certain row. By changing the start, you can select a rectangle and scroll that. But, 
you’ll need to think about what happens to the bottom line, or the scroll will just copy it 
out again in the same place. 

You can write a BASIC partial scroll; but it’s much too slow to be interesting. 


SIDEWAYS SCROLL 


Here’s another useful routine in the same vein. It scrolls the whole screen sideways, as if 
the display were cylindrical. In each line of display the first character is pushed on to the 
stack, the rest shifted down, and then the first one is popped off again to the top end. 
This is repeated for all lines of display. 


LOOP: 


LDA,0 

3E00 


set loop count 

LD HL, (D-FILE) 

2A0C40 



initialize 

INC HL 

23 



for block 

LDD,H 

54 



transfer of 

LDE,L 

5D 



first line 

INCHL 

23 

_ 



PUSH AF 

F5 

Zh 

save loop count 

LD A, (DE) 

lA 




PUSH AF 

F5 




LD BC,31dec 

01 1F00 



rotate one 

LDIR 

ED B0 


— 

row one 

POP AF 

FI 



space left 

DEC HL 

2B 




LD (HL), A 

77 

. 1 ^ 



POPAF 

FI 

> 

increment 

INCA 

3C 

loop count 

INC HL 3 TIMES 

23 23 23 

> 

adjust for 

INC DE TWICE 

1313 

next row 

CP A, 22 dec 

FE 16 

> 

jump unless 

JRNZ LOOP 

20 E A 

loop count is on 
last row 
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To see this at its best, embed it in a BASIC loop so that the screen scrolls repeatedly; 
and give it a nice display to scroll. For instance 


212 FORI = 0TO21 

214 PRINT AT I, I; “SCROLL” 

216 NEXT I 

220 LETY = USR(B-hD) 

222 GOTO 220 

Note that in machine code you can print to the 22nd and 23rd rows of screen, normally 
reserved for error messages; so you could change the next-to-last line of machine code to 

CP A, 24 dec FE 18 

Note that if you use a 24-row screen as part of a BASIC program, it is possible for the 
bottom two lines to interfere with the operating system and cause a crash, in some 
circumstances. 

For yet another example of block transfer, see DOWNLOAD, Appendix 7. 


MNEMONICS 


The next thing I should mention is that some people use slightly different mnemonic 
opcodes from those I’ve described. For instance, where I would write LD A, (nn) some 
people write LD (nn). This is because the A-register is the only register which can be 
loaded directly, so it’s not strictly necessary to specify it. I find that actually quoting it 
every time is a useful aid to memory, though. 


ALTERNATE REGISTERS 


I said that there is an alternate set of registers, and then promptly ignored them. You can 
always get away without using them, and they aren’t very useful anyway. You can’t do 
arithmetic in them. Their main use is to save temporarily the contents of the main set 
while you’re executing some routine which alters the main register contents in ways you 
don’t want. This is done by exchanging the contents of the main and alternate sets 
before, and again after, the offending routine: 


EX AF, AF' 

08 

swap AF with AF' 

EXX 

D9 

swap BC, DE, HL with BC', DE', HL' 

CALL. . . 

CD- 

call offending routine 

EX AF, AF' 

08 


EXX 

D9_| 

restore registers 


Of course, you could do the same thing by PUSHing the register contents you want saved 
on to the stack before the CALL, and POPping them off afterwards. 

In compute-and-display (SLOW) mode the 1000 operating system makes use of the 
A' and F' registers, so only use these if you’re running in FAST. Also, the IX register is 
used—so for indexing use lY. In the same vein, my LOADER program assumes that it’s 
always necessary to load the I and lY registers with IE and 4000, as the Sinclair Manual 
says; but this is usually unnecessary, and you may be able to omit these commands. But 
the RET is necessary. 



FLAGS 


I steered clear of the technicalities of the F-register; but here’s a brief summary: for more 
details consult one of the machine code books in the bibliography. 

There is room in the F-register for eight flags; but it only uses six of its available bits. 
The flags are: 


c 

Carry flag 

z 

Zero flag 

s 

Sign flag 

P/V 

Parity/Overflow flag 

H 

Half-Carry flag 

N 

Subtract flag 


These are arranged in the register like this: 


s 

Z 

X 

[S 

X 

P/V i 

N 

[C] 


where X means “not used”. 

The Carry flag is affected mainly by add, subtract, rotate and shift commands, and 
we’ve already seen how it works. 

The 2^ro flag is affected by a tremendous number of commands. Roughly, if anything 
(except LD, INC, DEC) changes the contents of A, then the Zero flag is set (to 1) if A is 
zero, and reset (to 0) otherwise. BIT sets the flag if the specified bit is zero. CP sets or 
resets the flag according to the result of a comparison. 

The Sign flag stores the sign bit of the result of whichever operation has just been 
carried out: 1 for negative, 0 for positive. 

T^e P/V flag works differently on arithmetic or logical commands. In arithmetic, it is 
set if there is an overflow in 2’s complement arithmetic (e.g. if the sum of two positive 
numbers runs off the end of the accumulator, giving an apparently negative result). For a 
logical operation it is set to 0 if the byte in A has an even number of bits equal to 1; and to 
1 if the number of bits equal to 1 is odd. The odd/even character of the number of bits 
equal to 1 is called the parity of the byte. 

The H and N flags are used only for binary coded decimal calculations, and can be 
ignored. 


ROM ROUTINES 


I have also been guilty of reinventing the wheel now and then. The point is that the 
BASIC interpreter in ROM has to call on routines such as those we’ve developed. So 
why not simply call them, rather than write our own? In general, the answer is that it 
would have been much more sensible to do so, since it saves a lot of effort and, almost as 
im{x>rtant, computer memory. But—so far as this book is concerned, my aim has been to 
tell you about Z80 machine code, and avoid, as far as possible, the special features of the 
1000. If all the examples had consisted of a series of calls to addresses in ROM you 
wouldn’t have learnt much! Of course, to use the ROM routines, you need to know 
where they are. Ian Logan’s book Sinclair ZX81 ROM Disassembly is good for this. 
While I’m on the subject of books, Toni Baker’s Mastering Machine Code on your ZX81 
is a good read. It goes into much more detail than I have had space for here, but at a 
faster pace: and it makes heavy use of ROM routines. 




EFFICIENT USE OF MACHINE CODE 


Finally, I want to tie up two loose ends I left hanging right at the beginning. I said that 
there may be reasons other than BASIC’s need to interpret statements each time they 
are executed for a machine code program to run faster than BASIC. I’ll explain with an 
example: 


BASIC 

Machine code 

10 FORI = 20TO1STEP-1 

LDB,14 

LOOP- 

50 NEXT I 

DJNZ LOOP 


In each case, every time the loop is executed a variable is decremented by 1. But that 
process is much more complicated in BASIC than it is in machine code. The reason is 
that since BASIC has to deal with decimal values some of the time, it assumes that it’s 
doing so all the time, and so it actually subtracts 1.00000000, which is no easier than 
subracting 1.58712684. In fact, the procedure employed is quite complex and time- 
consuming. The machine code, on the other hand, uses a single, purpose-built instruc¬ 
tion. The result is in the region of 100 times faster. 

The other point I deferred was that machine code can occupy more memory than its 
BASIC equivalent. Here’s an example which illustrates why: 


BASIC Machine code 

30 IFR = PANDP = OTHEN 

LETP = W LDHL,5000 

LD A, (HL) 

LD HL, 5001 
SUB A, (HL) 
JRNZ NEXTBIT 
LD HL, 5001 
LD A, (HL) 

LD HL, 5002 
SUB A, (HL) 
JRNZ NEXTBIT 
LD HL, 5001 
LD A, (5003) 

LD (HL), A 

NEXTBIT: 


No. of bytes 


3 

1 

3 

1 

2 

3 

1 

3 

1 

2 

3 

3 

J_ 

27 TOTAL 


The machine code assumes that R, P, Q and W are held in the bytes 5000,5001,5002 and 
5003, respectively. In practice it wouldn’t be as simple as that because each number will 
occupy 5 bytes and the SUB will actually be a CALL to a floating point subtraction 
routine. In any event, the actual code would need at least as many, and probably more 
than, the 27 bytes shown. The equivalent BASIC line occupies only 18 bytes, 1 for each 
of the symbols (IF, =, W, AND, and so on), 4 for the line number and 1 for the line 
delimiter. The more complex the BASIC statement, the more memory overhead there is 
in the machine code version. 
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OTHER PLACES TO STORE MACHINE CODE 


The main disadvantage with storing code above RAMTOP is that you can’t save it. The 
advantage is that you can load other stuff in under it. But, to save the code, there are 
alternatives. 

A favourite trick is to store the whole thing in a REM statement, the first line in the 
BASIC program. The first character after the REM has address 16514. So you write your 
BASIC starting with 

1 REM XXXXXX ... X 

with enough Xs to hold the code; and then POKE the machine code in. I used this when 
telling you about CHECK IN, at the start of this section. The code is accessed by RAND 
USR 16514 (or LET Y = USR 16514, etc.) and can be saved; also it is not destroyed by 
RUN. 

For your delectation. Appendix 7 gives a machine code program DOWNLOAD 
which, combined into HELPA, will automatically put the code into a REM statement— 
even in another program! 

Another place to store the code is in a character string, which is easily located (via the 
system variable VARS) provided you make this the first variable declared—e.g. start 
with a big enough string array: 

1 DIMAS (79) [to hold 79 bytes] 

and then put the machine code into A$ (1), A$ (2), etc. as you build up the string. The 
start address is 6 + PEEK 16400 + 256 * PEEK 16401. The main disadvantage is that 
RUN or CLEAR will wipe out your code. And the start address can sometimes wander. 
On the other hand, while you can safely LIST a REM statement (even if the result makes 
little sense) it’s wisest not to EDIT it, or try to write a new line into the same place to get 
rid of it. In certain circumstances (mostly if it’s a long piece of code) you can cause a crash 
this way. 


DEBUGGING 

There are no built-in debugging facilities in machine code; and while HELPA will help 
you edit code, it isn’t really designed to debug. (Nor are several other programs 
advertised as useful for “debugging” machine code!) Your best bet at this stage is to 
dry-run the routine using old-fashioned pencil and paper (see Timex/Sinclair 1000, 
p. 60). Of course you can insert tracing statements into machine code, but watch out for 
changes in addresses and jump-sizes. 

One useful (though apparently cackhanded) trick is to write your routine in BASIC 
first, and debug that: use only BASIC instructions that correspond to the machine code. 
(That is, emulate the machine code in BASIC.) It will work slowly, if at all; but it’s 
debuggable. 

For the really ambitious, this suggests a project. The idea is to improve HELPA by 
adding a routine SINGLE-STEP which will work through the program command by 
command, displaying the registers on the screen. You’ll need to (a) write a machine code 
routine to PUSH all registers on to the stack, then display them on the screen in hex; 
(b) add to this a routine that looks for a keyboard input; (c) write between each line of 
machine code a CALL to this routine (use the ** delimiters in HELPA to signal where); 
(d) work out how to return to BASIC if you want. 

For (b) you will need a ROM routine at address 02BB (called by CD BB 02) which puts 
into the HL register some numbers that depend on the key currently being pressed: for 
example key Z gives FBFE. (You now have all you need, but to save time, there’s 
another routine at 07BD which puts the character code into HL, if the result of 02BB is 
first loaded into BC.) There’s a lot more to it than this: I suggest you only try to write this 
if you’ve followed everything else in this book. 
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DRY-RUNNING A LINE-RENUMBER ROUTINE 


As an example of debugging using a dry run. I’ll tell you about my first stab at a routine to 
renumber the lines of a BASIC program, and how it got debugged. Being the first stab, I 
didn’t try for anything fancy: just a routine to go through the BASIC program and 
number the lines 10, 20, 30, . . . going up in 10s. Once I got that working, I reckoned I 
could fancy it up (arbitrary start and finish, arbitrary step size, etc.). 

Now to do this, you need to know how the BASIC lines are stored in memory. They 
occupy a block of addresses starting at 16509 and ending immediately before the value 
stored in D-FILE. And each line takes the following form: 


NS 


NJ 


U 


LS 


Code for line, including tokens 


ENTER 


Here NS and NJ are the senior and junior bytes of the line number (in 2-byte hex) and 
p, LS are the junior and senior bytes of the number of characters in the BASIC 
instruction on that line. Note the order of junior and senior bytes—it’s not an error. 

For example (we’ll need this for the dry-run) the program 


1 REM 
5 PRINT A 
is stored as follows: 


Address 

Contents 

Comments 

16509 

0 

Senior byte of first line number 

16510 

1 

Junior byte of first line number 

16511 

2 

Junior byte of length of line 

16512 

0 

Senior byte of length of line 

16513 

234 

Token for REM 

16514 

118 

ENTER 

16515 

0 

Senior byte of second line number 

16516 

5 

Junior byte of second line number 

16517 

3 

Junior byte of line length 

16518 

0 

Senior byte of line length 

16519 

245 

Token for PRINT 

16520 

38 

Code for A 

16521 

118 

ENTER 

16522 

118 

ENTER that starts display file 

16523 

0 

First character in display file 


You should check all this by typing in the little test program above and PEEKing 16509, 
etc. in command mode. Also, check that D-FILE holds 16522 by asking for PRINT 
PEEK 16396 + 256 * PEEK 16397. 

Now, our task is to search through the BASIC area looking for line numbers, and 
changi ng t hem. Note that (apart from 16509-10) the line numbers are the two bytes after 
an ENTER. So the idea is to look for ENTERs, increment, and change two bytes* 
repeat, keep going till you reach the end of the BASIC area. 
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This led to the following code: 


LD HL, (D-FILE) 2A 0C 40 

LDBC, 16509 017D40 

SBCHL,BC ED 42 

LDB, H 44 

LDC, L 4D 

DEC BC 0B 

LDHL, 16509 21 7D40 

LDDE, 10DEC 110A00 

JR: RENUMBER 18 16 

LOOP: LDA,0 3E00 

CPA, B B8 

JRNZSKIP 2005 

CPA, C B9 

JRNZSKIP 2002 

JR END 18 IB 

SKIP: INCHL 23 

DECBC 0B 

PUSH BC C5 

LDA,(HL) 7E 

LD,B, ENTER 0676 

CPA, B B8 

POPBC Cl 

JRNZLOOP 20 EC 

FOUND: INCHL 23 

DECBC 0B 

RENUMBER: LD (HL), D 72 

INCHL 23 

DECBC 0B 

LD(HL),E 73 

PUSH HL E5 

LDHL, 10 DEC 210A00 

ADCHL,DE ED5A 

LD D, H 54 

LD E, L 5D 

POPHL El 

JR LOOP 18 DB 

END: [standard ending] 
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The first block of code sets up HL to the start address 16509 and loads BC with the length 
of the BASIC area: to guard against trouble at the end BC is decremented here. LOOP is 
the dogsbody; it first checks to see if BC has got down to 0 yet; and if not, searches for an 
ENTER. If it finds one it passes on to FOUND, which moves HL on one place ready for 
RENUMBER. This changes the line number, and adds 10 to DE ready for the next line. 
Once BC hits 0, the routine goes to END. 

Well, that was the theory. In practice, it led to a decorative crash. 

So what was wrong? 

To find out, I did a dry-run on the little test program. This is summarized, in a rather 
cryptic form, below: the idea is to track through step by step and see what happens to the 
registers, the stack, and the data in the BASIC area. As you work through, successive 
lines list how the registers change; but to save space I’ve put a lot of stuff on one line 
when I can. You’ll need pencil and paper: build up the table yourself, comparing it with 
mine. 



[At this point there is a jump to RENUMBER. Addresses 16509 and 16510 get the new 
values 0,10. .. meanwhile the registers go like this:] 


A 

F 

B 

c 

D E 

H L 

1 STACK 



0 

11 


16510 


16510 






10 







20 

20 








16510 


_ 

0 

/ 








X 

0 

10 


16511 

0 

10 

2 


118 







X 

0 

10 





0 

y 








X 

0 

9 


16512 

0 

9 

0 


118 







X 

0 

9 




_ 

0 

y 








X 

0 

8 


16513 

0 

8 

234 


118 







X 

0 

8 




_ 

0 

y 








X 

0 

7 


16514 

0 

7 

118 

y 

118 



1 
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[Having found an ENTER, the routine continues into FOUND and RENUMBER: 
addresses l65l5 and 16516 get the new line number 20; and the dry-run continues:] 


A 

F 

B C 

I D E 

i 

H L 

STACK 



0 

7 





0 

6 

16515 




0 

5 

16516 






10 

16516 




30 

30 






16516 

— 

0 

y 






X 

0 

4 

16517 

0 4 

3 


118 





X 

0 

4 


— 

0 

y 






X 

0 

3 

16518 

0 3 

0 


118 





X 

0 

3 


— 

0 

y 






X 

0 

2 

16519 

0 2 

245 


118 





X 

0 

2 


— 

0 

y 






X 

0 

1 

16520 

0 1 

38 


118 




(*) 

X 

0 

1 


_ 

0 

y 






X 

0 

0 

16521 

0 0 

118 


118 





And now (if you’ve followed this far!) we see we’re in trouble. BC has got down to 
zero just too late; the program is about to wander into the display file and start operating 
on that; and it’s missed the jump to END. The problem? BC was one too big to start 
with! If BC had been one smaller, we’d have hit zero at the line marked (*) and finished. 

The remedy: decrement BC one more, between lines 7 and 8 of the machine code 
routine, so that DEC BC ... 0B gets repeated. That’s all! 
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Try it out. Load the revised routine above RAMTOP, as usual; hit NEW; write in a 
program with irregular line numbers like 


73 

REM 

122 

PRINT P 

8001 

RETURN 

8002 

PLOT 3,5 

8003 

REM 

9997 

STOP 


and then ask for RAND USR 32512 (or wherever you’ve put it). 

If you’ve got HELPA running, use it to renumber HELPA. It’s amazingly fast. 

As it stands, the routine isn’t perfect. It doesn’t do anything about GOTO or GOSUB 
line numbers; so after renumbering you’ll have an editing job to do. There’s also a more 
subtle bug: a long enough line can have a 118 in its “length of line” bytes; and the routine 
as written will go haywire here. So here are two projects: protect against the long-line 
bug; and work out how to deal with GOTOs and GOSUBs automatically. 

A final moral: observe where the error arose. Not in the complicated part of the 
routine, where the main work was done: but in the condition for the work to end. This 
kind of “boundary problem” is a constant source of errors in programming. Unless you 
work out very care^lly indeed the precise “edges” of what you’re trying to do, you can 
easily get lost in the wilderness. 
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Appendices 










2 Memory Reservation Tables 

To reserve 256-byte blocks with 16K of RAM, the addresses are as shown. Leave the 
contents of address 16388 at zero. 


No. of 256-byte 
blocks 

Size of area 
reserved 

POKE 

16389 

Start address of area 

Decimal 

Hex 

0 

0 

128 

32768 

8000 

1 

256 

127 

32512 

7F00 

2 

512 

126 

32256 

7E00 

3 

768 

125 

32000 

7D00 

4 

1024 

124 

31744 

7C00 

5 

1280 

123 

31488 

7B00 

6 

1536 

122 

31232 

7A00 

7 

1792 

121 

30976 

7900 

8 

2048 

120 

30720 

7800 

9 

2304 

119 

30464 

7700 

10 

2560 

118 

30208 

7600 

11 

2816 

117 

29952 

7500 

12 

3072 

116 

296% 

7400 

13 

3328 

115 

28440 

7300 

14 

3584 

114 

29184 

7200 

15 

3840 

113 

28928 

7100 

16 

40% 

112 

28672 

7000 

17 

4352 

111 

28416 

6F00 

18 

4608 

110 

28160 

6E00 

19 

4864 

109 

27904 

6D00 

20 

5120 

108 

27648 

6C00 
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3 System Variable Addresses 

This table gives the hex and decimal addresses for a number of useful system variables— 
see the Timex Manual for their functions. 


Variable 

No. of 
bytes 

Hex 

Decimal 

ERR-SP 

2 

4002 

16386 

RAMTOP 

2 

4004 

16388 

D-FILE 

2 

400C 

16396 

DF-CC 

2 

400E 

16398 

VARS 

2 

4010 

16400 

E-LINE 

2 

4014 

16404 

STKBOT 

2 

401A 

16410 

STKEND 

2 

401C 

16412 

BERG 

1 

401E 

16414 

MEM 

2 

401F 

16415 

LAST-K 

2 

4025 

16421 

SEED 

2 

4032 

16434 

FRAMES 

2 

4034 

16436 

MEMBOT 

30 

405D 

16477 

(RAMTOP usual value IK) 

2 

4400 

17408 

(RAMTOP usual value 16K) 

2 

8000 

32768 
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4 Summary of Z80 Commands 

This is a list of all the opcode mnemonics, with a summary of their effects. Those 
commands explained more fully in the text are given a page reference. The effects on the 
flags are omitted: for these, consult the Zilog Reference Card or the books listed in the 
bibliography under “Machine Code”. 


ADC 

Page 137 

ADD 

Page 128 

AND 

Page 134 

BIT 

Page 144 

CALL 

Page 118 


CCF 

CP 

Page 134 

CPD 

Page 152 

CPDR 

Page 152 

CPI 

CPIR 

CPL 

DAA 

Page 152 
Page 152 

DEC 

DI 

DJNZ 

Page 136 

Page 137 

El 

EX 

Page 155 

EXX 

Page 155 

HALT 


IM 

IN 

INC Page 136 

IND, INDR. INI. INIR 

JP 

Page 135 

JR 

Page 135 

LD 

LDD 

Page 126 


Add, including the carry flag. Store in A or HL. 

Add, ignoring the carry flag. Store in A or HL. 

Logic AND on corresponding bits: store in A. 

BIT b, r sets the Zero flag according to the value of the b-th bit 
of the byte in register r. The bits are in the order 76543210 
within each byte. 

Calls a subroutine. There are conditional calls signalled by the 
additional letters C (call if the Carry flag is set); M (if the Sign 
flag is set—“the result (of a compare) is negative”); NC (if the 
Carry flag is not set); NZ (if the Zero flag is not set); P (if the 
Sign flag is not set—“the result is positive”); PE (if the Parity 
flag is set: ignore this one); PO (if the Parity flag is not set: 
ignore this too); Z(if the Zero flag is set). For flags, see Page 
134,156. 

Complement Carry flag (i.e. swap 0 and 1). 

Compare: sets the flags as if it were a subtraction from A, but 
leaves A unchanged. 

Compare and decrement. Compare through HL; then decre¬ 
ment HL and BC. 

Compare, decrement, repeat: block search. Like CPD but 
repeating until either the result of the comparison is 0, or BC 
reaches 0. 

Like CPD except that HL increments; BC still decrements. 
Like CPDR but incrementing HL. 

Complement (flip bits of) the A-register. 

Decimal adjust accumulator. Used in binary-coded decimal 
work: ignore. 

Decrement: reduce value by 1. 

Disable interrupts. Ignore. 

Decrement, jump if non-zero. Decrement B and jump rela¬ 
tive unless the Zero flag is set. Used in loops like a BASIC 
FOR/NEXT. 

Enable interrupts. Ignore. 

Exchange values. Instructions with (SP) exchange the regis¬ 
ters HL, IX or lY with the top of the stack. 

Exchange all three register-pairs BC, DE, HL with their 
alternates BC', DE', HL'. 

Wait for an interrupt. Unless you’ve got hardware attached, 
and know what you’re doing, DO NOT USE as the program 
will wait forever. 

Interrupt mode: ignore. 

Input from a device. Ignore. 

Increment: increase value by 1. 

Input commands analogous to LDD, LDDR, LDI, LDIR. 
Ignore. 

Jump. Variants with added C, M, NC, NZ, P, PE, PO, Z are 
conditional jumps, with conditions as for CALL. 

Jump relative—followed by a 1-byte displacement. Condi¬ 
tional variants are C, NC, NZ, Z only. 

Load. Can use all five addressing modes. 

Not the same as LD D! Load what HL points to into what DE 
points to: decrement BC, DE, HL. 
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LDDR 


Page 152 Load, decrement, repeat: block transfer. Do LDD until BC 
hits zero. Copies a block of memory whose length is stored in 
BC, out of what HL points to and into what DE points to. 


LDI 

Page 152 

Like LDD except that HL and DE increment: BC still dec¬ 
rements. 

LDIR 

Page 152 

Like LDDR except that HL and DE increment. 

NEC 

Negative: change the sign of the contents of A. 

NOP 


No operation. Do nothing for 1 time-cycle—i.e. waste time. 
Useful for temporary deletion of instructions when debug¬ 
ging: harmless and helpful. 

OR 

Page 134 Logic OR on bits. Store in A. 

OTDR, OTIR, OUT, 


OUTD,OUn 

Various outputs. Ignore. 

POP 

Page 138 

Pop from stack into indicated register. 

PUSH 

Page 138 

Push from register on to stack. 

RES 


Reset a bit—i.e. make it zero. 

RET 

Page 118 

Return from subroutine. Conditional returns, corresponding 
to the possibilities for CALL, are possible. (Conditions on a 
CALL need not match those on a RET!) 

RETI, RETN 


Return from interrupt subroutines. Ignore. 

RL 


Rotate left: like a shift, except that the carry flag is included as 
if it were bit number 8. 

RLA 


Rotate left accumulator. Like RL A but with a different effect 
on the flags. 

RLC 


Not the same as RL C! Rotate left, but put bit 7 into carry and 
into bit 0. 

RLCA 


Like RLC A, but same flag difference as RLA. 

RLD 


Not what you’d expect at all: rotate left decimal. Used for 
binary coded decimal: ignore. 

RR 


Like RL but to the right. 

RRA 


Like RLA. 

RRC 


Like RLC. 

RRCA 


Like RLCA. 

RRD 


Like RLD. 

RST 


Like CALL, but only from addresses 0,8,10,18,20,28,30,38 
(hex). These are all in the ROM on the ZX81: see Ian Logan’s 
books in the Bibliography. RST 0 is like temporarily discon¬ 
necting the power. 

SBC 

Page 137 

Subtract, taking account of the carry flag. Store in A or HL. 

SCF 


Set carry flag (to 1). 

SET 


Set a bit—i.e. make it 1. 

SLA 

Page 137 

Shift left arithmetic. All bits move up 1; bit 0 becomes 0. 

SRA 

Page 137 

Shift right arithmetic. Move bits down 1; copy bit 7 into 6 and 
7. 

Shift right logical. Move bits down 1 place; make bit 7 zero. 

SRL 

Page 137 

SUB 

Page 128 Subtract, ignoring carry. Store in A. (There is no SUB HL, r 
command: if you want one, reset the Carry flag and use SBC. 

XOR 

Page 134 Exclusive or on each bit. Store in A. 
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5 Z80 Opcodes 

'Hiis is a complete list of Z80 opcodes, arranged alphabetically by mnemonic. In the 
listing, the symbol n stands for any single-byte number; nn for any 2-byte number; and d 
is 1-byte displacement written in 2’s complement notation. Note that all 2-byte numbers 
are encoded with the junior byte preceding the senior. 

Examples: 

LD BC, nn has the opcode 01 nn, so LD BC, 732F codes as01 2F73. 
LDA,(IY + d)" " " FD7Ed,soLDA(IY + 07) " "FD7E07. 

The table of opcodes is based on one published by Zilog Inc. A listing numerically by 
opcode is included in the Timex Manual Appendix A: note the use of lower case letters 
there for mnemonics. 


ADC A, (HL) 

8E 

ADC A, (IX+ d) 

DDBEd 

ADC A, (lY + d) 

FDBEd 

ADC A, A 

8F 

ADCA,B 

88 

ADCA,C 

89 

ADCA,D 

8A 

ADCA,E 

8B 

ADCA.H 

8C 

ADCA,L 

8D 

ADCA,n 

CEn 

ADC HL, BC 

ED4A 

ADC HL, DE 

ED5A 

ADCHL, HL 

ED6A 

ADC HL, SP 

ED7A 

ADDA, (HL) 

86 

ADDA, (IX+ d) 

DD86d 

ADDA, (lY + d) 

FD86d 

ADD A, A 

87 

ADDA,B 

80 

ADDA,C 

81 

ADDA,D 

82 

ADDA,E 

83 

ADDA,H 

84 

ADDA,L 

85 

ADDA,n 

C6n 

ADD HL, BC 

09 

ADDHUDE 

19 

ADD HL, HL 

29 

ADD HL, SP 

39 

ADD IX, BC 

DD09 

ADD IX, DE 

DD19 

ADD IX, IX 

DD29 

ADD IX, SP 

DD39 

ADD lY, BC 

FD09 

ADD lY, DE 

FD19 

ADD lY, lY 

FD29 

ADD lY, SP 

FD39 

AND(HL) 

A6 

AND (IX+ d) 

DDA6d 

AND (lY + d) 

FDA6d 

AND A 

A7 

ANDB 

AO 

ANDC 

A1 

ANDD 

A2 

ANDE 

A3 

ANDH 

A4 

ANDL 

A5 

ANDn 

E6n 

BITO, (HL) 

CB46 

BITO, (IX+ d) 

DDCBd46 

BITO, (lY + d) 

FDCBd46 

BITO, A 

CB47 

BIT0,B 

CB40 

BIT0,C 

CB41 

BIT0,D 

CB42 

BIT0,E 

CB43 

BIT0,H 

CB44 

BIT0,L 

CB45 

BIT1,(HL) 

CB4E 

BIT1,(IX + d) 

DDCBd4E 

Bm,(IY + d) 

FDCBd4E 


BIT1,A 

CB4F 

BIT1,B 

BC48 

BIT1,C 

CB49 

BIT1,D 

CB4A 

BIT1,E 

CB4B 

BIT1,H 

CB4C 

BIT1,L 

CB4D 

BIT 2, (HL) 

CB56 

BIT 2, (IX+ d) 

DDCBdSe 

BIT2,(IY + d) 

FDCBdSe 

BIT 2, A 

CB57 

BIT2,B 

CB50 

BIT2,C 

CB51 

BIT2,D 

CB52 

BIT2,E 

CB53 

BIT2,H 

CB54 

BIT2,L 

CB55 

BIT 3, (HL) 

CB5E 

BIT 3, (IX+ d) 

DDCBdSE 

BIT3,(IY-i-d) 

FDCBdSE 

BIT 3, A 

CB5F 

BIT3,B 

CB58 

BIT3,C 

CB59 

BIT3,D 

CB5A 

BIT3,E 

CB5B 

BIT3,H 

CB5C 

BIT3,L 

CB5D 

BIT4,(HL) 

CB66 

BIT 4, (IX+ d) 

DDCBd66 

BIT4,(IY + d) 

FDCBd66 

BIT 4, A 

CB67 

BIT4,B 

CB60 

BIT4,C 

CB61 

BIT4,D 

CB62 

BIT4,E 

CB63 

BIT4,H 

CB64 

BIT4,L 

CB65 

BITS, (HL) 

CB6E 

BIT 5, (IX+ d) 

DDCBd6E 

BITS, (lY + d) 

FDCBd6E 

BIT 5, A 

CB6F 

BIT5,B 

CB68 

BIT5,C 

CB69 

BIT5,D 

CB6A 

BIT5,E 

CB6B 

BIT5,H 

CB6C 

BIT5,L 

CB6D 

BIT6,(HL) 

CB76 

BITS, (IX+ d) 

DDCBd76 

BIT 6, (lY + d) 

FDCBd76 

BIT 6, A 

CB77 

BIT6,B 

CB70 

BIT6,C 

CB71 

BIT6,D 

CB72 

BIT6,E 

CB73 

BIT6,H 

CB74 

BIT6,L 

CB75 

BIT 7, (HL) 

CB7E 

BIT 7, (IX+ d) 

DDCBd7E 

BIT 7, (lY + d) 

FDCBd7E 

BIT 7, A 

CB7F 

BIT7,B 

CB78 


BIT7,C 

CB79 

BIT7,D 

CB7A 

BIT7,E 

CB7B 

BIT7,H 

CB7C 

BIT7,L 

CB7D 

CALLC, nn 

DCnn 

CALLM, nn 

FCnn 

CALL NC, nn 

D4nn 

CALLnn 

CDnn 

CALL NZ, nn 

C4nn 

CALLP, nn 

F4nn 

CALL PE, nn 

ECnn 

CALLPO, nn 

E4nn 

CALLZ, nn 

CCnn 

CCF 

3F 

CP(HL) 

BE 

CP(IX + d) 

DDBEd 

CP(IY + d) 

FDBEd 

CPA 

BF 

CPB 

B8 

CPC 

B9 

CPD 

BA 

CPE 

BB 

CPH 

BC 

CPL 

BD 

CPn 

FEn 

CPD 

EDA9 

CPDR 

EDB9 

CPI 

EDA1 

CPIR 

EDB1 

CPL 

2F 

DAA 

27 

DEC(HL) 

35 

DEC (IX + d) 

DD3Sd 

DEC(IY + d) 

FD35d 

DEC A 

3D 

DECB. 

05 

DECBC 

OB 

DECC 

OD 

DECD 

15 

DECDE 

IB 

DECE 

ID 

DECH 

25 

DECHL 

2B 

DEC IX 

DD2B 

DECIY 

FD2B 

DECL 

2D 

DECSP 

3B 

Dl 

F3 

DJNZ,d 

lOd 

El 

FB 

EX (SP), HL 

E3 

EX(SP), IX 

DDE3 

EX(SP),IY 

FDE3 

EXAF,AF' 

06 

EXDE,HL 

EB 

EXX 

D9 

HALT 

76 

IMO 

ED46 

IM1 

E056 

IM2 

E05E 

INA,(C) 

ED78 
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INA,(n) 

DBn 

IN B, (C) 

ED40 

INC, (C) 

ED48 

IN D, 1C) 

ED50 

IN E, (C) 

ED58 

IN H, (C) 

ED60 

INL.(C) 

ED68 

INC (HL) 

34 

INC (IX + d) 

DD34d 

INC (lY + d) 

FD34d 

INCA 

3C 

INCB 

04 

INC BC 

03 

INCC 

OC 

INCD 

14 

INC DE 

13 

INCE 

1C 

INCH 

24 

INC HL 

23 

INC IX 

DD23 

INC lY 

FD23 

INCL 

2C 

INCSP 

33 

IND 

EDAA 

INDR 

EDBA 

INI 

EDA2 

INIR 

EDB2 

JP(HL) 

E9 

JP(IX) 

DDES 

JP(IY) 

FDE9 

JPC, nn 

DAnn 

JPM.nn 

FAnn 

JP NC, nn 

D2nn 

JPnn 

C3nn 

JP NZ, nn 

C2nn 

JP P, nn 

F2nn 

JP PE, nn 

EAnn 

JPPO, nn 

E2nn 

JPZ, nn 

C^nn 

JRC,d 

38d 

JR,d 

18d 

JRNC,d 

30d 

JR NZ, d 

20d 

JRZ,d 

28d 

LD(BC),A 

02 

LD(DE),A 

12 

LD (HL),A 

77 

LD (HL),B 

70 

LD(HL).C 

71 

LD (HL), D 

72 

LD (HL),E 

73 

LD(HL),H 

74 

LD(HL).L 

75 

LD (HL),n 

36n 

LD (IX + d), A 

DD77d 

LD (IX + d), B 

DD70d 

LD(IX + d).C 

DD71d 

LD (IX + d), D 

DD72d 

LD (IX + d),E 

DD73d 

LD (IX + d), H 

DD74d 

LD (IX + d), L 

DD75d 

LD(IX + d),n 

DD36dn 

LD (IY + d),A 

FD77d 

LD(IY + d),B 

FD70d 

LD(IY + d),C 

FD71d 

LD(IY + d),D 

FD72d 

LD(IY + d),E 

FD73d 

LD(IY + d),H 

FD74d 

LD (IY + d),L 

FD75d 

LD(IY + d),n 

FD36dn 

LD(nn), A 

32nn 

LD (nn), BC 

ED43nn 

LD(nn), DE 

ED53nn 

LD (nn). HL 

22nn 

LD (nn), IX 

DD22nn 

LD(nn). lY 

FD22nn 

LD(nn), SP 

ED73nn 

LDA,(BC) 

OA 

LDA, (DE) 

1A 

LDA, (HL) 

7E 

LDA,(IX + d) 

DD7Ed 

LDA, (lY + d) 

FD7Ed 

LDA,(nn) 

3Ann 

LDA, A 

7F 

LDA,B 

78 


LDA,C 

79 

LDA,D 

7A 

LDA,E 

7B 

LDA,H 

7C 

LDA,I 

ED57 

LDA.L 

7D 

LDA,n 

3En 

LDB, (HL) 

46 

LD B, (IX+ d) 

DD46d 

LD B, (lY + d) 

FD46d 

LD B,A 

47 

LD B,B 

40 

LDB,C 

41 

LD B,D 

42 

LD B,E 

43 

LD B,H 

44 

LD B,L 

45 

LDB,n 

06n 

LD BC, (nn) 

ED4Bnn 

LD BC, nn 

01 nn 

LDC, (HL) 

4E 

LDC.(IX + d) 

DD4Ed 

LDC,(IY + d) 

FD4Ed 

LD C,A 

4F 

LDC,B 

48 

LDC,C 

49 

LDC.D 

4A 

LDC.E 

4B 

LDC,H 

4C 

LDC,L 

4D 

LDC,n 

OEn 

LDD, (HL) 

56 

LD D.(IX + d) 

DD56d 

LD D,(IY + d) 

FD56d 

LD D,A 

57 

LD D,B 

50 

LD D,C 

51 

LD D,D 

52 

LD D,E 

53 

LD D,H 

54 

LD D,L 

55 

LD D.n 

16n 

LD DE.(nn) 

ED5Bnn 

LD DE, nn 

linn 

LD E, (HL) 

5E 

LDE.(IX + d) 

DD5Ed 

LD E. (lY + d) 

FD5Ed 

LDE,A 

5F 

LD E,B 

58 

LD E,C 

59 

LD E,D 

5A 

LD E,E 

5B 

LDE.H 

5C 

LD E.L 

5D 

LDE,n 

lEn 

LD H, (HL) 

66 

LDH,(IX + d) 

DD66d 

LD H. (lY + d) 

FD66d 

LD H,A 

67 

LD H,B 

60 

LD H.C 

61 

LD H.D 

62 

LDH,E 

63 

LD H,H 

64 

LD H,L 

65 

LD H,n 

26n 

LD HL. (nn) 

2 Ann 

LD HL, nn 

21nn 

LD l,A 

ED47 

LD IX, (nn) 

DD2Ann 

LD IX. nn 

DD21nn 

LD lY, (nn) 

FD2Ann 

LD lY, nn 

FD21nn 

LD L, (HL) 

6E 

LD L, (IX + d) 

DD6Ed 

LD L, (lY + d) 

FD6Ed 

LD L,A 

6F 

LD L,B 

68 

LD L.C 

69 

LD L,D 

6A 

LD L,E 

6B 

LD L.H 

6C 

LD L,L 

6D 

LD L.n 

2En 

LDSP.(nn) 

ED7Bnn 


LD SP, HL 

F9 

LDSP, IX 

DDF9 

LDSP, lY 

FDF9 

LD SP, nn 

31 nn 

LDD 

EDA8 

LDDR 

EDB8 

LDI 

EDAO 

LDIR 

EDBO 

NEC 

ED44 

NOP 

00 

OR (HL) 

B6 

OR (IX + d) 

DDB6d 

OR (lY + d) 

FDB6d 

ORA 

B7 

ORB 

BO 

ORC 

B1 

ORD 

B2 

ORE 

B3 

ORH 

B4 

ORL 

B5 

ORn 

F6n 

OTDR 

EDBB 

OTIR 

EDB3 

OUT(C),A 

ED79 

OUT(C),B 

ED41 

OUT(C),C 

ED49 

OUT(C).D 

ED51 

OUT(C),E 

ED59 

OUT(C),H 

ED61 

OUKO.L 

ED69 

OUT(n),A 

D3n 

OUTD 

EDAB 

OUTI 

EDA3 

POPAF 

FI 

POPBC 

Cl 

POP DE 

D1 

POPHL 

El 

POP IX 

DDE1 

POP lY 

FDE1 

PUSH AF 

F5 

PUSH BC 

C5 

PUSH DE 

D5 

PUSH HL 

E5 

PUSH IX 

DDE5 

PUSH lY 

FDE5 

RES0,(HL) 

CB86 

RES0.(IX + d) 

DDCBd86 

RES 0, (lY + d) 

FDCBd86 

RES 0,A 

CB87 

RESO.B 

CB80 

RESO.C 

CB81 

RESO.D 

CB82 

RESO.E 

CB83 

RESO.H 

CB84 

RESO.L 

CB85 

RES1,(HL) 

CB8E 

RES1,(IX + d) 

DDCBd8E 

RES1.(IY + d) 

FDCBd8E 

RES1.A 

CB8F 

RESI.B 

CB88 

RES1.C 

CB89 

RES1,D 

CB8A 

RES1.E 

CB8B 

RES1,H 

CB8C 

RES1,L 

CB8D 

RES 2. (HL) 

CB96 

RES 2, (IX+ d) 

DDCBd96 

RES 2.(IY + d) 

FDCBd96 

RES 2, A 

CB97 

RES 2, B 

CB90 

RES 2.C 

CB91 

RES 2,D 

CB92 

RES 2,E 

CB93 

RES 2, H 

CB94 

RES 2, L 

CB95 

RES 3, (HL) 

CB9E 

RES 3, (IX + d) 

DDCBd9E 

RES 3, (lY + d) 

FDCBd9E 

RES 3, A 

CB9F 

RES 3, B 

CB98 

RES3,C 

CB99 

RES3,D 

CB9A 

RES 3,E 

CB9B 

RES 3, H 

CB9C 

RES 3,L 

CB9D 
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RES4,(HL) 

CBA6 

RES 4, (IX+ d) 

ODCBdAe 

RES 4, (lY + d) 

FOCBdAG 

RES 4, A 

CBA7 

RES4,B 

CBAO 

RES4,C 

CBA1 

RES4,D 

CBA2 

RES4,E 

CBA3 

RES 4, H 

CBA4 

RES4,L 

CBA5 

RES 5, (HL) 

CBAE 

RES 5,(IX + d) 

DDCBdAE 

RES 5, (lY + d) 

FDCBdAE 

RES 5, A 

CBAF 

RES 5, B 

CBA8 

RES 5,C 

CBA9 

RES 5, D 

CBAA 

RES 5,E 

CBAB 

RES 5, H 

CBAC 

RES 5,L 

CBAD 

RES6,(HL) 

CBB6 

RES 6, (IX + d) 

DDCBdBB 

RES 6.(IY + d) 

FDCBdBB 

RES 6, A 

CBB7 

RES 6, B 

CBBO 

RES 6, C 

CBB1 

RES 6, D 

CBB2 

RES 6, E 

CBB3 

RES 6, H 

CBB4 

RES6,L 

CBB5 

RES 7,(HL) 

CBBE 

RES 7, (IX + d) 

DOCBdBE 

RES 1 , (lY + d) 

FDCBdBE 

RES 7, A 

CBBF 

RES 7,B 

CBB8 

RES 7,C 

CBB9 

RES 7, D 

CBBA 

RES 7, E 

CBBB 

RES 1 , H 

CBBC 

RES 1 , L 

CBBD 

RET 

C9 

RETC 

D8 

RETM 

F8 

RETNC 

DO 

RETNZ 

CO 

RETP 

FO 

RET PE 

E8 

RETPO 

EO 

RETZ 

C8 

RETI 

ED4D 

RETN 

ED45 

RL(HL) 

CB16 

RL(IX + d) 

DDCBdie 

RL(IY + d) 

FDCBdie 

RLA 

CB17 

RLB 

CB10 

RLC 

CB11 

RLD 

CB12 

RLE 

CB13 

RLH 

CBM 

RLL 

CB15 

RLA 

17 

RLC (HL) 

CB06 

RLC (IX + d) 

DDCBdOe 

RLC (lY + d) 

FDCBdOe 

RLC A 

CB07 

RLCB 

CBOO 

RLCC 

CB01 

RLCD 

CB02 

RLCE 

CB03 

RLCH 

CB04 

RLCL 

CB05 

RLCA 

07 

RLD 

ED6F 

RR (HL) 

CB1E 

RR (IX + d) 

DDCBdIE 

RR (lY + d) 

FDCBdIE 

RRA 

CB1F 

RRB 

CB18 

RRC 

CB19 

RRD 

CB1A 

RRE 

CB1B 

RRH 

CB1C 

RRL 

CB1D 

RRA 

IF 


RRC (HL) 

CBOE 

RRC (IX + d) 

DDCBdOE 

RRC (lY + d) 

FDCBdOE 

RRC A 

CBOF 

RRCB 

CB08 

RRCC 

CB09 

RRCD 

CBOA 

RRCE 

CBOB 

RRCH 

CBOC 

RRCL 

CBOD 

RRC A 

OF 

RRD 

ED67 

RSTO 

C7 

RST10H 

D7 

RST18H 

DF 

RST20H 

E7 

RST28H 

EF 

RST30H 

F7 

RST38H 

FF 

RST 8 

CF 

SBCA,(HL) 

9E 

SBC A, (IX+ d) 

DD9Ed 

SBCA,(IY + d) 

FD9Ed 

SBC A, A 

9F 

SBCA,B 

98 

SBCA,C 

99 

SBCA,D 

9A 

SBCA,E 

9B 

SBCA,H 

9C 

SBCA,L 

9D 

SBCA,n 

DEn 

SBC HL, BC 

ED42 

SBC HL, DE 

ED52 

SBC HL,HL 

ED62 

SBC HL, SP 

ED72 

SCF 

37 

SETO,(HL) 

CBC6 

SETO,(IX + d) 

DDCBdCe 

SETO,(IY + d) 

FDCBdCe 

SETO,A 

CBC7 

SETO,B 

CBCO 

SETO,C 

CBC1 

SETO,D 

CBC2 

SETO,E 

CBC3 

SETO,H 

CBC4 

SETO,L 

CBC5 

SET1,(HL) 

CBCE 

SET1,(IX + d) 

DDCBdCE 

SET1,(IY + d) 

FDCBdCE 

SET1,A 

CBCF 

SET1,B 

CBC8 

SET1,C 

CBC9 

SET1,D 

CBCA 

SET1,E 

CBCB 

SET1,H 

CBCC 

SET1,L 

CBCD 

SET 2, (HL) 

CBD6 

SET 2, (IX+ d) 

DDCBdDe 

SET2,(IY + d) 

FDCBdDS 

SET 2, A 

CBD7 

SET2,B 

CBDO 

SET2,C 

CBD1 

SET2,D 

CBD2 

SET2,E 

CBD3 

SET2,H 

CBD4 

SET2,L 

CBD5 

SET3,B 

CBD8 

SET 3. (HL) 

CBDE 

SET 3, (IX+ d) 

DDCBdDE 

SET 3, (lY + d) 

FDCBdDE 

SET 3, A 

CBDF 

SET3,C 

CBD9 

SET3,D 

CBDA 

SET3,E 

CBDB 

SET3,H 

CBDC 

SET3,L 

CBDD 

SET 4, (HL) 

CBE6 

SET4,(IX + d) 

DDCBdEe 

SET4,(IY + d) 

FDCBdEe 

SET 4, A 

CBE7 

SET4,B 

CBEO 

SET4.C 

CBE1 

SET4,D 

CBE2 

SET4,E 

CBE3 

SET4,H 

CBE4 


SET4,L 

CBES 

SETS, (HL) 

CBEE 

SETS, (IX+ d) 

DDCBdEE 

SETS, (lY + d) 

FDCBdEE 

SETS, A 

CBEF 

SETS,B 

CBE8 

SETS,C 

CBE9 

SETS,D 

CBEA 

SETS,E 

CBEB 

SETS,H 

CBEC 

SETS,L 

CBEO 

SET 6, (HL) 

CBF6 

SET 6, (IX+ d) 

DDCBdFe 

SET 6, (lY + d) 

FDCBdFe 

SET 6, A 

CBF7 

SET6,B 

CBFO 

SET6,C 

CBF1 

SET6,D 

CBF2 

SET6,E 

CBF3 

SET6,H 

CBF4 

SET6,L 

CBFS 

SET 7, (HL) 

CBFE 

SET 7, (IX+ d) 

DDCBdFE 

SET 7, (lY + d) 

FDCBdFE 

SET 7, A 

CBFF 

SET7,B 

CBF8 

SET7,C 

CBF9 

SET7,D 

CBFA 

SET7,E 

CBFB 

SET7,H 

CBFC 

SET7,L 

CBFO 

SLA(HL) 

CB26 

SLA (IX+ d) 

ODCBd26 

SLA (lY + d) 

FDCBd26 

SLAA 

CB27 

SLAB 

CB20 

SLAC 

CB21 

SLAD 

CB22 

SLAE 

CB23 

SLAH 

CB24 

SLAL 

CB2S 

SRA(HL) 

CB2E 

SRA (IX + d) 

DDCBd2E 

SRA (lY + d) 

FDCBd2E 

SRA A 

CB2F 

SRAB 

CB28 

SRAC 

CB29 

SRAD 

CB2A 

SRAE 

CB2B 

SRAH 

CB2C 

SRAL 

CB2D 

SRL (HL) 

CB3E 

SRL (IX + d) 

DDCBd3E 

SRL(IY + d) 

FDCBd3E 

SRL A 

CB3F 

SRLB 

CB38 

SRLC 

CB39 

SRLD 

CB3A 

SRLE 

CB3B 

SRLH . 

CB3C 

SRLL 

CB3D 

SUB (HL) 

96 

SUB (IX + d) 

DD96d 

SUB (lY + d) 

FD96d 

SUB A 

97 

SUBB 

90 

SUBC 

91 

SUBD 

92 

SUBE 

93 

SUBH 

94 

SUBL 

9S 

SUBn 

D6n 

XOR (HL) 

AE 

XOR (IX + d) 

DDAEd 

XOR (lY + d) 

FDAEd 

XOR A 

AF 

XORB 

A8 

XORC 

A9 

XORD 

AA 

XORE 

AB 

XORH 

AC 

XORL 

AD 

XORn 

EEn 
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6 HELPA 

This is a versatile utility program, written in BASIC for easy modification, to help you 
run machine code. The acronym stands for Hex Editor, Loader, and Partial Assembler. 
A full listing is given below: here’s how to use it. 

1. On first use, after typing it in and debugging, SAVE using GOTO 1400 and hit 
NEWLINE. It will then be automatically saved under the “default” name HELPA. 

2. On LOAD or RUN it will first ask whether you have reserved memory space. If so 
type “Y”; if not, “N”. In the latter event it will now automatically (and without 
disturbing the BASIC program) reset RAMTOP to give a multiple of 256 bytes spare 
space, asking you for this multiple. The program will halt with a listing: ignore this and 
type RUN, this time answering “Y”. The value now in RAMTOP will be printed. (For 
example, hit “N” and then “2”, followed by “RUN”: RAMTOP goes to 32256; see 
Appendix 2 for a table of values.) This resetting of RAMTOP uses the PRINT USR1040 
trick, avoiding the use of NEW. 

3. It now types HEX CODE: and gives you a cursor 0 . 

4. You may now type in (and, using control commands described below, manipulate) 
machine code in hex. As each code group is keyed in, the program strips it of any blank 
spaces (which means you can use these as you want), splits it into two-character codes, 
and prints out these in a 10-column display. A final ** delimiter is added on the end of 
each group; the cursor moves to the end of the code just input. 

For example, the input “□AinE23nn4” is printed out as 

A1E2 34** S 

(and so would “A1E234” or “AlDE2n34” be). 



HELPA engaged in loading the Partial Scroll routine: about to input the final instruction 20 ED. 

5. The next group of codes may now be input, and will be automatically appended 
immediately after the cursor position. The **s are for the user’s convenience only and 
are ignored when the code is loaded above RAMTOP, so the groups do not have to 
correspond to Z80 instruction groups; however this helps for checking. 

6. In addition, “control” instructions may be input. These must be the first symbol in 
their group; subsequent characters are usually ignored except in a few cases described 
below. These control commands are rather like ZEDTEXT mnemonics, but the codes 
and functions differ. 
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The control commands are: 


G 

(Go) 

Run the machine code routine 

L 

(Load) 

Load the machine code routine above RAMTOP 

M 

(Move) 

Move cursor forward 

N 

(Negative) 

Move cursor backward 

P 

(Print) 

Print out current hex listing 

R 

(Relative) 

Used for automatic calculation of relative jumps 

S 

(Save) 

Save program 

X 

(eXcise) 

Delete from the listing 


More detailed descriptions follow in a more convenient order. 

M, N The command Mn, where n is a number, moves the cursor forward n spaces. 
Nn moves it back n spaces. It is protected against going off the listing. If n is 
omitted it will be set to 1. 

X A command Xn where n is a number ^ 0 will delete the next n pairs of 
characters (including **s) after the cursor. The display will not be affected 
until P is pressed. If n is omitted it will be set to 1. 

To append text, just set the cursor to a position immediately in front of 
where it should go, and enter it. Everything beyond will be shifted up to 
make room, but only the new text displayed until P is pressed. 

P Prints the current text, and moves the cursor to the top. 

S Saves the program, including the current hex listing. There is an option 

allowing you to name the program as you wish. To run a saved program, 
SAVE it before typing “L” and “G”. Then LOAD into BASIC, type 
GOTO 200 {not RUN!!), then “L”, then “G”. 

L Loads the machine code, stripped of superfluous ** delimiters, above 
RAMTOP, starting at the RA^^OP value you’ve set; tacks on the stan¬ 
dard ending including the final RET command. 

G This runs the routine. On typing “G” the machine will ask for the number of 

data bytes (i.e. bytes before the start address) and will then run the program 
once this has been input. Control returns to HELP A (barring a crash!). 

R A useful feature to make relative jumps easy: these are a nuisance by hand 
because of the need to count displacements and put them into 2’s comple¬ 
ment hex; but nice for programs because of portability. It works like this. 
{a) Input the machine code routine setting all relative jump sizes to 00. 
{b) To change to the correct value for a given jump, set the cursor 
immediately in front of the 00, and delete by hitting “X”. Now input Rn 
where the number n is the (decimal) position of the destination byte for the 
jump, read off from the screen display as follows. Number the rows and 
columns of the hex code array starting at 0, like this: 

0123456789 


1 

2 

3 


and set n = xy for row x, column y. (That is, for the byte in row 17, column 5, 
type R175.) The fact that there are 10 columns makes it easy to read off the 
numbers. [You could modify the program so that the cursor is moved to the 
destination, and the jump found from that: in practice this is slower, 
because of all the cursor-shifting you have to do.] 

(c) Now press “P” for a revised display with the correct jump size 
included. 

{d) Locate the cursor before the next relative jump size, and repeat. 
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{e) Note that the program automatically adjusts for any **s around and 
gives the 2’s complement code needed: if the jump is outside permissible 
range, it will say so. 



HELP A setting up a relative jump in the Video Inversion routine: before . . . 



. . . and after. 

(f) This may sound complicated, so here’s an example, using the Video 
Inverter program on page 147. Set RAMTOP for one 256-byte block; input 
in turn the groups 

0616 

2A0C40 


176 


10 F3 






but use 00 on the JR, JRZ, and DJNZ commands. The display will be: 

RAMTOP = 32512 
HEX CODE: 

06 16 **2A0C40 23 **7E 

**FE76 ** 28 00 **C680 ** 

77 ** 18 W ** 10 W ** 0 

Here the underlined 00s are the relative jump sizes to be set. Using “N”, get 
the cursor in front of the last 00 like this 

77** 1800** 10 1^ 00** 

and then type “X” to delete the 00. (The screen will not change, however— 
yet!) The instruction here is DJNZ LOOP, and the destination LOOP starts 
with the code 23. This is in row 0, column 7; so input R7. After a short pause 
the screen will be printed out with the new display, and the 00 will have 
changed to F3, as required. 

Back the cursor to the 2800; delete; input R25 (because SKIP is the group 
10 FE starting in row 2, column 5). Now we get 28 05. And so on. 

Now for the program listing. 

5 REM IhELPAI copyright IAN STEWART AND 
ROBIN JONES 1982. 

10 PRINT “HAVE YOU RESERVED MEMORY?” 

20 INPUT A$ 

30 IF A$ = “” THEN GOTO 50 
40 IF A$ (1) = “N” THEN GOTO 9000 
50 CLS 

60 LET RT = PEEK 16388 + 256 * PEEK 16389 
70 PRINT “RAMTOP = □”; RT 
80 PRINT “HEX CODE:” 

100 LET Cl = 0 
110 LETH$ = “” 

120 GOSUB400 

130 DIM F (20) 

131 LETF(1) = 700 

132 LET F (6) = 800 

133 LET F (7) = 900 

134 LET F (8) =1000 

135 LETF(10)= 1100 

136 LETF(11)= 1200 

137 LETF(12) = 1300 

138 LETF(13) = 1400 

139 LETF(14) = 1500 
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140 

200 

210 

220 

230 

240 

250 

260 

300 

310 

320 

330 

340 

350 

360 

400 

410 

420 

450 

460 

470 

500 

510 

520 

600 

610 

620 

630 

640 

650 

660 

700 

710 

720 

730 

740 

750 

760 

800 

810 


LETF(18) = 1600 
INPUT 1$ 

LETA = 0 


LETA = A + 1 

IF A > LEN1$ THEN GOTO 300 
IF 1$ (A) < > THEN GOTO 220 

LET 1$ = 1$ (TO A - 1) + 1$ (A + 1 TO) 

GOTO 230 

IF CODE 1$ (1) > = 44 THEN GOTO 500 
LETI$ = I$ + “**” 

LET H$ = H$ (TO 2 * Cl) + 1$ + H$ (2 * Cl + 1 TO) 

GOSUB 450 

GOSUB 600 

GOSUB 400 

GOTO 200 


REM PRINT CURSOR 


PRINT AT 2 + INT (CI/10), 3 * (Cl - 10 * INT (CI/10)); “ 0 ’ 
RETURN 


REM UNPRINT CURSOR 


PRINT AT 2 + INT (CI/10), 3 * (Cl - 10 * INT (CI/10)); 

RETURN 

REM I ROUTINES I 

GOSUB F (CODE 1$ (1) - 43) 

GOTO 200 

REM I PRINT APPENDED TEl^ 

FORJ = lTOLENI$/2 
PRINTI$(2*J- lT02*J) + “n”; 

LETCI = CI + 1 

IF Cl = 10 * INT (CI/10) THEN PRINT 
NEXT! 

RETURN 
REM I GO I 
CLS 

PRINT “NUMBER OF DATA BYTES?" 

INPUT D 
CLS 

LETY = USR(RT+ D) 

RETURN 
REM I LOAD I 

LETH$ = H$ + “3E1EED47FD210040C9” 




820 LETJ = RT-1 
830 LETI=-1 
840 LETJ = J + 1 


850 

860 

870 

880 

890 

900 

910 

920 

930 

940 

950 

960 

970 

1000 

1010 

1020 

1030 

1040 

1050 

1060 

1070 

1100 

1110 

1120 

1130 

1140 

1150 

1160 

1170 

1185 

1187 

1190 

1192 

1195 

1300 

1310 

1320 


LETI = l + 2 

IF I > LEN1$ THEN RETURN 

IF H$ (I) = THEN GOTO 850 

POKE J, 16 * (CODE H$ (I) - 28) + CODE H$ (I + 1) - 28 

GOTO 840 

REM I MOVE CURSOR POSITIVELYl 
GOSUB 450 

IF LEN 1$ = 1 THEN LET CM = 1 


IF LEN 1$ > 1 THEN LET CM = VAL1$ (2 TO) 
LET Cl = Cl + CM 

IF Cl > LEN H$/2 THEN LET Cl = LEN H$/2 

GOSUB 400 

RETURN 


REM MOVE CURSOR NEGATIVELY 


GOSUB 450 

IF LEN 1$ = 1 THEN LET CM = 1 

IF LEN 1$ > 1 THEN LET CM = VAL 1$ (2 TO) 

LET Cl = Cl-CM 

IF Cl < 0 THEN LET Cl = 0 

GOSUB 400 

RETURN 


REM [PRINT 
CLS 


PRINT “RAMTOP = □ RT 
PRINT “HEX CODE: ” 

PRINT 

LETCI = 0 ■ 

FORJ= lTOLENH$/2 
PRINT H$ (2 * J - 1 TO 2 * J) + 

LET Cl = Cl + 1 

IF Cl = 10* INT(CI/10) THEN PRINT 
NEXT! 

GOSUB 400 
RETURN 

REM I RELATIVE JUMPS 
LETJCI = VAL 1$ (2 TO) 

LET IS = JCI - Cl - 1 
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1195 RETURN 

1300 REM [relative JUMPS) 

1310 LETJCI = VALI$(2TO) 

1320 LETJS = JCI-CI-1 
1325 GOSUB2000 

1330 IF JS > = - 128 AND JS < = 127 THEN GOTO 1357 
1335 CLS 

1340 PRINT AT 10,6; “INVALID JUMP SIZE” 

1345 FORQ=1TO20 

1346 NEXTQ 
1350 GOSUB1100 
1355 RETURN 

1357 IF JS < 0 THEN LET JS = JS + 256 
1360 LETX1 = INT(JS/16) 

1365 LETX0 = JS-16*X1 

1367 LET X$ = CHR$ (XI + 28) + CHR$ (X0 + 28) 

1370 LETH$ = H$(T02*CI) + X$ + H$(2*CI + ITO) 

1375 LETCI = CI + 1 

1380 GOSUB1100 

1390 RETURN 

1400 REM I save! 

1410 PRINT “ ISAVEI . INPUT PROGRAM NAME. 

DEFAULT NAME HELPA.” 

1420 INPUT N$ 

1430 IF N$ = THEN LET N$ = “HELPA” 

1440 SAVEN$ 

1450 CLS 

1460 GOTO 10 

1600 REM I DELETE 

1610 IF LEN1$ = 1 THEN LET K = 1 

1620 IF LEN 1$ > 1 THEN LET K = VAL1$ (2 TO) 

1630 LET H$ = H$ (TO 2 * Cl) + H$ (2 • Cl + 2 ‘K + 1 TO) 
1640 RETURN 

2000 REM I ASTERISK ADJUST 
2010 IFJS<0THENLET 

W$ = H$(2*JCI+ 1T02*CI) 

2020 IF JS > = 0 THEN LET W$ = H$ (2 * Cl + 1 TO 2 * JCI) 

2030 LET SC = 0 

2040 FORT = 1 TO LEN W$ 

2050 IF W$ (T) = THEN LET SC = SC + 1 




2060 

2070 

2080 

2090 

9000 

9010 

9020 

9030 

9040 

9050 

9060 

9070 


NEXTT 


IF JS < 0 THEN LET JS = JS + SC/2 
IF JS > 0 THEN LET JS = JS - SC/2 


RETURN 


REM I RESERVE MEMORYI 


PRINT “HOW MANY 256-BYTE BLOCKS?” 
INPUT NB 

PRINT “AFTER LIST PRESS RUN” 

FORT= 1TO20 

NEXTT 

POKE 16389,128 - NB 
PRINT USR 1040 


Remarks: In this program, the machine code is manipulated and stored in a string H$. 
Sections of code are input via a string 1$. The cursor position is determined by Cl; the 
position of a relative jump by JCI. The various subroutines are identified by REM 
statements. 
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7 DOWNLOAD 

This is a useful addition to HELP A, which allows you to incorporate HELPA-assembled 
machine code into BASIC programs (which may be loaded from tape if desired) in a 
form which can be SAVEd. It uses a piece of machine code, also loaded above 
RAMTOP, which downloads your machine code into a pre-prepared REM statement in 
the BASIC program area. Note that absolute addresses will have to be changed after¬ 
wards using POKE, and are best avoided, unless you write the routine using the 
addresses that will be needed after downloading. 

First, the machine code: it uses (very fast) block transfers. 


CODELENGTH 

-(two bytes to be POKEd) 

LD HL, (RAMTOP) 

2A(M40 

LDC, (HL) 

4E 

INCHL 

23 

LD B, (HL) 

46 

DECHL 

2B 

LD DE, 4082 

118240 

PUSHBC 

C5 

LD BC, 29 decimal 

01 ID 00 

ADDHL, BC 

09 

POPBC 

Cl 

LDIR 

ED B0 

LD A, IE 

3E IE 

LDI, A 

ED 47 

LD IY,4(W0 

FD210040 

RET 


C9 

Build it into HELPA by adding the following BASIC program lines: 

141 

LET F (17) = 3000 


3000 

REM IdOWNLOADI COPYRIGHT IAN STEWART AND 


ROBIN JONES 1982. 


3010 

LETLH = 0 


3020 

FOR I = 1 TO LEN H$ 

3030 

IF H$ (I) < > THEN LET LH = LH + 1 

3040 

NEXT I 


3050 

LETLH = LH/2 + 9 


3060 

PRINT AT 21,0; “LENGTHD LH; “□BYTES.” 

3070 

LETH$ = ‘‘00002A04404E23462B118240C5011D0009C1 


EDB03E1EED47FD210040C9” + H$ 

3080 

GOSUB 800 


3090 

LETLS = INT(LH/256) 

3100 

LETU = LH-256* 

LS 

3110 

POKE RT, U 


3120 

POKERT+ 1,LS 


3130 

RETURN 



Use this extra facility as follows. 
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1. Write your machine code routine (let’s name it YOURROUTINE for reference— 
it’s the routine you want to make use of in a BASIC program, not anything to do with 
DOWNLOAD) using HELPA, exactly as before; but do not press “L” or “G”. 

2. Press “W” on a HELPA input, once you’re happy with the code. 

3. Hit NEW, or LOAD in your BASIC routine. 

4. Make the first line of the BASIC read 

1. REM XXXXXXXX .. . XX 

where the number of Xs is at least the length of YOURROUTINE (the number printed 
out as LENGTH . . . BYTES above). Don’t forget that the “standard ending” adds 9 
bytes. The routine above allows for these, but you may wonder where the displayed 
number comes from! 

5. Input from the keyboard in command mode 

RAND USR (value of RAMTOP + 2). 

For example, with 256 bytes reserved, this is RAND USR (32514). If you’ve forgotten, 
type 

RAND USR (PEEK 16388 + 256 * PEEK 16389 + 2). 

The + 2 is crucial. 

6. You will now find that line 1 of the BASIC has changed: it contains your YOUR¬ 
ROUTINE code. You can run YOURROUTINE as a subroutine from BASIC by the 
command RAND USR 16514 + number of data bytes. (Incidentally those RANDS are 
just a convenient way to call USR, which is a function: LET Y = USR 16514 is just as 
good but uses more space and time.) The 16514 isn’t magic: it’s the address of the first 
byte after the REM in line 1. You must make the REM statement the first in the BASIC 
code. (At least, by the time you work out why this isn’t quite true, you’ll also know what 
else you can do.) 

7. Now write the rest of your BASIC program around this. 

8. Warning: You can LIST, or even LIST 1, without doing any harm—even if the 
REM runs over a full screen. The listing will look pretty weird, but no matter. However, 
do not attempt to erase line 1 by typing in a new linel; and don’t try to EDIT line 1. You 
can, under certain conditions, cause a crash and have to start all over again. You can edit 
all other lines, though. 

9. The resulting BASIC program can be SAVEd as usual, and will run perfectly . . . 
provided you’ve written it correctly! 

DOWNLOAD does a rather interesting thing: it passes a routine from one program, 
stored on one tape, to a different program stored on another tape. It so happens this is 
easier in machine code than BASIC . . . but a nice project is to work out how to do the 
same kind of job on BASIC routines. The resetting of RAMTOP, and loading of a copy 
of the relevant routine above it, is the key step; then load the new one and download the 
routine. But, in BASIC, watch out for the operating system! The line numbers, in 
particular, are a problem. 

Note that you can use DOWNLOAD to store several machine code routines in a long 
enough REM: just type them out end-to-end using HELPA. Press “L”, the “P” after 
each for the standard ending. The 16514 has to change, according to which routine you 
want: just add 16514 to the number of bytes before the starting byte. 
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Timex Sinclair 1000 

Programs, Games, and Graphics 

by Ian Stewart and Robin Jones 

“Far and away the best book for ZX81 [TS 1000] users new to computing.” 

— Popular Computing 


Control Your TRS80 

Better BASIC and Machine Code 

by Ian Stewart and Robin Jones 


Available in the Fall, 1983 — 

Introducing the TS 2000 

by Ian Stewart and Robin Jones 

Introduction to the Commodore 64 
A Complete Guide to Understanding Your New 
Computer 

by Nevin Scrimshaw 

Easy Programming with TI BASIC 

by Cortland Shurtliff 

Discover the VIC-21/VIC-20 

An All-Purpose Guide to Your Personal Computer 

by Cortland Shurtliff 
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In their first book, Timex Sinclair 1000: Programs, Games, and 
Graphics, Ian Stewart and Robin Jones wrote one of the most charm¬ 
ing and humorous introductory computer books available. Now, in 
Machine Code and Better BASIC, this crack computer team embarks 
on yet more adventurous forays into the computer universe. 

Although written for the TS 1000 and TS 2000, the principles of good 
programming are machine-independent, and almost everything in this 
book applies to any machine built around a Z80 or Z80A CPU: the 
Sharp MZ80B or MZ80K, the Tandy TRS80, and the ZX81. Machine 
Code and Better Basic introduces structured BASIC programming. It 
also allows you to go outside BASIC altogether, with Machine Code, 
the language of the Z80 microchip. And one of the bonuses of 
Machine Code is that it teaches you more about the way the computer 
actually works. 

Some programs include: 

• searching a stock list 

• enqueuing and dequeuing data 

• a complete word processor 

• even a test for French vocabulary 





. . . and more. 


There are Machine Code routines to: 

_ • give the display a checkerboard pattern 

• turn it into inverse video 

• add and multiply numbers 

• move data around in RAM 


H 


. . . and even more. 


With this book in hand, you’ll be ready to show the computer who’s boss! 
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